home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr12
/
pplasc.zip
/
PPL3.ASC
< prev
Wrap
Text File
|
1993-06-04
|
234KB
|
6,630 lines
MODEM() Function
Function
Access the connect string as reported by the modem.
Syntax
MODEM()
No arguments are required
Return Type & Value
STRING Returns the modem connect string.
Remarks
PCBoard expects and requires certain information to be reported
by the modem anytime a user connects to the BBS. The minimum
requirement is a string with the word CONNECT; other information
may be included, such as the connect speed, error correction,
data compression, etc. Should your PPL application have need of
this information as well, it may be accessed with this function.
Examples
FAPPEND 1,"MODEM.LOG",O_WR,S_DW
FPUTLN 1,LEFT(U_NAME(),30)+MODEM()
FCLOSE 1
See Also
MONEY Type
Function
Declare one or more variables of type money.
Syntax
MONEY var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])]
var The name of a variable to declare. Must start with
a letter [A-Z] which may be followed by letters, digits [0-9] or
the underscore [_]. May be of any length but only the first 32
characters are used.
arr The name of an array variable to declare. The same
naming conventions as var are used.
s The size (0-based) of an array variable dimension.
Any constant integer expression is allowed.
Remarks
MONEY variables are stored as positive or negative cents. The
range of MONEY is $-21,474,836.48 through $+21,474,836.47. It
is stored internally as a four byte signed long integer. If
MONEY is assigned to or from an INTEGER type then the cents (-
2,147,483,648 - +2,147,483,647) are assigned. If MONEY is
assigned to a STRING type then it is automatically converted to
the following format: "$sD.CC", where s is the sign (- for
negative amounts, nothing for positive amounts), D is the dollar
amount (one or more digits as needed) and CC is the cents amount
(00-99). If a STRING is assigned to MONEY then PPL will do it's
best to convert the string back to the appropriate amount of
money. All other types, when assigned to or from MONEY, will be
converted to an INTEGER first before being assigned to or from
the MONEY type.
Examples
MONEY itemAmt, subTot, total, priceList(2,17)
See Also
BOOLEAN Type, DATE Type, INTEGER Type, STRING Type, TIME Type
MONTH() Function
Function
Extracts the month of the year from a specified date.
Syntax
MONTH(dexp)
dexp Any date expression.
Return Type & Value
INTEGER Returns the month from the specified date expression
(dexp). Valid return values are from 1 to 12.
Remarks
This function allows you to extract a particular piece of
information about a DATE value, in this case the month of the
date.
Examples
PRINTLN "This month is: ",MONTH(DATE())
See Also
DAY() Function, DOW() Function, YEAR() Function
MORE Statement
Function
Pause the display and ask the user how to continue.
Syntax
MORE
No arguments are required
Remarks
It is often necessary to pause in the display of information and
wait for the user to catch up. This statement allows you prompt
the user on how to continue. The acceptable responses are Y (or
whatever letter is appropriate for the users language selection)
to continue, N (or, again, whatever letter is appropriate) to
abort, or NS to continue in non-stop mode. It displays prompt
number 196 from the PCBTEXT file for the current language to let
the user know what is expected.
Examples
PRINTLN "Your account has expired!"
PRINTLN "You are about to be logged off"
MORE
PRINTLN "Call me voice to renew your subscription"
See Also
WAIT Statement
MPRINT/MPRINTLN Statements
Function
Print (write) a line to the caller's screen (modem) only (with
an optional newline appended).
Syntax
M P R I N Te x p [ , e x p ]
- o r -
MPRINTLN [exp[,exp]]
exp An expression of any type to evaluate and write to
the caller's screen.
Remarks
These statements will evalutate zero, one or more expressions of
any type and write the results to the modem for the caller's
display. The MPRINTLN statement will append a newline to the
end of the expressions; MPRINT will not. Note that at least one
expression must be specified for MPRINT, unlike the MPRINTLN
statement which need not have any arguments passed to it. These
statements only send information to the modem and do not
interpret @ codes; if the remote caller has ANSI then ANSI will
be interpreted.
Examples
MPRINT "The name of the currently running PPE file
is "
MPRINTLN PPENAME(),"."
MPRINT "The path where it is located is "
MPRINTLN PPEPATH(),"."
MPRINT "The date is ",DATE()," and the time is
",TIME(),"."
MPRINTLN
See Also
PRINT/PRINTLN Statements, SPRINT/SPRINTLN Statements
NC Constant
Function
To re-start the display of information according to the current
mode.
Value
0 = 0b = 0o = 0h
Remarks
The STARTDISP statement takes a single argument to start
displaying information in a certain format. FCL tells PCBoard
to count lines and pause as needed during the display of
information. FNS tells PCBoard to not stop during the display
of information. NC instructs PCBoard to start over with the
last specified mode (FCL or FNS).
Examples
INTEGER i,j
STARTDISP FCL
FOR i = 1 TO 5
STARTDISP NC
FOR j = 1 to 50
PRINTLN "This is line ",j
NEXT
NEXT
See Also
FCL Constant, FNS Constant
NEWLINE Constant
Function
Set the new line after prompt flag in an INPUTSTR, PROMPTSTR, or
DISPTEXT statement.
Value
64 = 1000000b = 100o = 40h
Remarks
The INPUTSTR, PROMPTSTR, and DISPTEXT statements have the
ability to send a carriage return/line feed after a prompt is
displayed automatically and without the need to make a separate
call to the NEWLINE statement.
Examples
STRING pwd
INPUTSTR "Enter
id",pwd,@X0E,4,"0123456789",LFBEFORE+NEWLINE+LFAFTE
R
IF (pwd <> "1234") PRINTLN "Bad id"
See Also
DISPTEXT Statement, INPUTSTR Statement, LFAFTER Constant,
LFBEFORE Constant, PROMPTSTR Statement
NEWLINE Statement
Function
Move the cursor to the beginning of the next line.
Syntax
NEWLINE
No arguments are required
Remarks
This statement should be used for moving to the beginning of the
next line on screen, scrolling if necessary. It will do so
regardless of the current cursor position, unlike the FRESHLINE
statement.
Examples
INTEGER i, end
LET end = RANDOM(20)
FOR i = 1 TO end
PRINT RIGHT(RANDOM(10000),8)
NEXT
FRESHLINE
NEWLINE
PRINTLN "Now we continue with a blank line between"
See Also
FRESHLINE Statement, NEWLINES Statement
NEWLINES Statement
Function
Execute a specified number of NEWLINE statements.
Syntax
NEWLINES count
count An integer expression with the number of times
to execute NEWLINE.
Remarks
This statement is convienient when executing multiple and/or
variable NEWLINE statements for screen formatting. It takes a
single integer expression argument and automatically executes
that many NEWLINE statements for you without the need to set up
a loop or to write multiple NEWLINE lines in your source code.
Examples
INTEGER i, end
LET end = RANDOM(20)
FOR i = 1 TO end
PRINT RIGHT(RANDOM(10000),8)
NEXT
FRESHLINE
NEWLINE 5
PRINTLN "Now we continue with a 5 blank lines
between"
See Also
FRESHLINE Statement, NEWLINE Statement
NEWPWD Statement
Function
Change the users password and maintain the password PSA if
installed.
Syntax
NEWPWD pwd,var
pwd A string expression with the new password for the
user.
var A variable to hold the password change status; TRUE
if the password was changed or FALSE otherwise.
Remarks
There are two ways to change the users password under PPL
control. The first is to simply use the GETUSER statement,
assign the new password to the U_PWD variable, then issue the
PUTUSER statement. However, this isn't adequate if the SysOp
has installed the password PSA. This statement will take care
of validating the password, checking it against the password
history, updating the password history, setting a new expiration
date if necessary and incrementing the times changed counter.
If the password fails a validity test then this statement will
set the var parameter to FALSE to let you know that the password
wasn't changed. If the password PSA isn't installed or if the
password conforms to the PSA requirements, then var will be set
to TRUE.
Examples
BOOLEAN changed
STRING pwd
INPUTSTR "Enter a new
password",pwd,@X0E,12,MASK_PWD(),ECHODOTS
NEWLINE
NEWPWD pwd,changed
IF (!changed) PRINTLN "Password not changed"
See Also
NOCHAR() Function
Function
Get the no response character for the current language.
Syntax
NOCHAR()
No arguments are required
Return Type & Value
STRING Returns the no character for the current language.
Remarks
Support for foreign language yes/no responses can be easily
added by using this function to determine what a negative
response should be instead of hardcoding the english "N"
character.
Examples
STRING ans
LET ans = YESCHAR()
INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO
IF (ans = NOCHAR()) END
See Also
YESCHAR() Function, YESNO Constant
NOCLEAR Constant
Function
Set the no clear input field flag in an INPUTSTR or PROMPTSTR
statement.
Value
1024 = 10000000000b = 2000o = 400h
Remarks
The INPUTSTR and PROMPTSTR statements have the ability to
automatically clear the default value from the input field when
the users presses his first key if ANSI is available. This is
the default mode of operations. If you don't want this to
happen, you may use this flag to disable this feature.
Examples
STRING cmds
LET cmds = "QUIT"
INPUTSTR
"Commands",cmds,@X0E,60,MASK_ASCII(),STACKED+NOCLEA
R
TOKENIZE cmds
LET cmds = GETTOKEN()
IF (cmds = "QUIT") END
KBDSTUFF cmds+TOKENSTR()
See Also
INPUTSTR Statement, PROMPTSTR Statement
NOT() Function
Function
Calculate the bitwise NOT of an integer argument.
Syntax
NOT(iexp)
iexp Any integer expression.
Return Type & Value
INTEGER Returns the bitwise NOT of iexp.
Remarks
This function may be used to toggle all bits in an integer
expression. Wherever a bit had been set it will be clear after
this function call, and vice versa.
Examples
' Toggle the bits
PRINTLN NOT(1248h)
' Toggle all flag
INTEGER flag
LET flag = NOT(flag)
See Also
AND() Function, OR() Function, XOR() Function
ONLOCAL() Function
Function
Determine whether or not a caller is on locally.
Syntax
ONLOCAL()
No arguments are required
Return Type & Value
BOOLEAN Returns TRUE if the caller is on locally, FALSE
otherwise.
Remarks
There are some features that work differently for local and
remote callers, such as file transfers and modem communications.
This function will report to you whether or not a user is logged
on locally and allow you to handle local processing differently
than remote processing.
Examples
IF (ONLOCAL()) THEN
PRINTLN "Call back verification cannot be
performed for"
PRINTLN "users logged in locally!"
END
ENDIF
CALL "CALLBACK.PPE"
See Also
OPENCAP Statement
Function
Open the screen capture file.
Syntax
OPENCAP file,stat
file A string expression with the filename to open.
stat A variable to hold the return status (TRUE if error
opening file, FALSE otherwise).
Remarks
PCBoard has the ability to capture screen output to a file for
later reference. PPL allows that same ability via the OPENCAP
and CLOSECAP statements. This could be useful in a program that
executes a series of commands in non-stop mode. The process
could open a capture file first, execute the commands, close the
capture file, then allow the user to view or download the
capture file. CLOSECAP closes the capture file and turns off
screen capturing. Also, the SHOWON and SHOWOFF statements can
be used to turn on and off showing information to the screen
while allowing that same information (even if not displayed or
transmitted via modem) to be captured to a file. The SHOWSTAT()
function can be used to check the current status of the SHOWON
and SHOWOFF statements.
Examples
BOOLEAN ss
LET ss = SHOWSTAT()
SHOWOFF
OPENCAP "CAP"+STRING(PCBNODE()),ocFlag
IF (ocFlag) THEN
DIR "U;NS"
CLOSECAP
KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13)
ENDIF
IF (ss) THEN
SHOWON
ELSE
SHOWOFF
ENDIF
See Also
CLOSECAP Statement, SHOWOFF Statement, SHOWON Statement,
SHOWSTAT() Function
OPTEXT Statement
Function
Set the text to be used by the @OPTEXT@ macro.
Syntax
OPTEXT str
str Any string expression.
Remarks
The @OPTEXT@ macro is used to include operation specific text in
prompts and display files. Normally PCBoard automatically fills
it in with the appropriate value. However, you can use it for
your own purposes by issuing this statement to set the text and
immediately displaying the information that should use it (by
either printing a line or displaying a file).
Examples
OPTEXT STRING(DATE())+" & "+STRING(TIME())
PRINTLN "The date and time are @OPTEXT@"
DISPFILE "FILE",GRAPH+SEC+LANG
See Also
OR() Function
Function
Calculate the bitwise OR of two integer arguments.
Syntax
OR(iexp1,iexp2)
iexp1 Any integer expression.
iexp2 Any integer expression.
Return Type & Value
INTEGER Returns the bitwise OR of iexp1 and iexp2.
Remarks
This function may be used to set selected bits in an integer
expression by ORing the expression with a mask that has the bits
to set set to 1 and the bits to ignore set to 0.
Examples
' Set the bits in the low byte
PRINTLN OR(1248h,00FFh)
' Randomly set a flag the hard way
INTEGER flag
LET flag = OR(RANDOM(1),RANDOM(1))
See Also
AND() Function, NOT() Function, XOR() Function
O_RD Constant
Function
Set the open for read access flag in a FCREATE/FOPEN/FAPPEND
statement.
Value
0 = 0b = 0o = 0h
Remarks
Files may be opened for read, write or combined read/write
access. You should only use the access you need to allow other
processes to open files at the same time in multitasking and
networked environments. This constant will allow your PPE to
read from a file without writing any information out to it.
Examples
FOPEN 1,"FILE.DAT",O_RD,S_DN ' Open for read access
FOR i = 1 TO 10
FGET 1,s
PRINTLN s
NEXT
FCLOSE 1
See Also
O_RW Constant, O_WR Constant
O_RW Constant
Function
Set the open for read and write access flag in a
FCREATE/FOPEN/FAPPEND statement.
Value
2 = 10b = 2o = 2h
Remarks
Files may be opened for read, write or combined read/write
access. You should only use the access you need to allow other
processes to open files at the same time in multitasking and
networked environments. This constant will allow your PPE to
both read from and write to a file without the need to close and
reopen it between accesses.
Examples
FOPEN 1,"FILE.DAT",O_RW,S_DN ' Open for read and
write access
FOR i = 1 TO 10
FPUT 1,"X"
FGET 1,s
PRINTLN s
NEXT
FCLOSE 1
See Also
O_RD Constant, O_WR Constant
O_WR Constant
Function
Set the open for write access flag in a FCREATE/FOPEN/FAPPEND
statement.
Value
1 = 1b = 1o = 1h
Remarks
Files may be opened for read, write or combined read/write
access. You should only use the access you need to allow other
processes to open files at the same time in multitasking and
networked environments. This constant will allow your PPE to
write to a file but will restrict read access.
Examples
FOPEN 1,"FILE.DAT",O_WR,S_DN ' Open for write
access
FOR i = 1 TO 10
FPUTLN 1,"Line ",i
NEXT
FCLOSE 1
See Also
O_RD Constant, O_RW Constant
PAGEOFF Statement
Function
Turn off the SysOp paged indicator.
Syntax
PAGEOFF
No arguments are required
Remarks
One of the features of PCBoard where change is often requested
is the operator page facility. Some people want to be able to
configure multiple ranges of availability per day, some want a
different sounding page bell, longer or shorter page attempts,
etc, etc. This statement, along with the CHAT and PAGEON
statements and the PAGESTAT() function, allow you to implement
an operator page in any way desired.
Examples
PAGEON
FOR i = 1 TO 10
PRINT "@BEEP@"
DELAY 18
IF (KINKEY() = " ") THEN
PAGEOFF
SHELL TRUE,i,"SUPERCHT",""
GOTO exit
ENDIF
NEXT
:exit
See Also
CHAT Statement, PAGEON Statement, PAGESTAT() Function
PAGEON Statement
Function
Turn on the SysOp paged indicator and update user statistics.
Syntax
PAGEON
No arguments are required
Remarks
One of the features of PCBoard where change is often requested
is the operator page facility. Some people want to be able to
configure multiple ranges of availability per day, some want a
different sounding page bell, longer or shorter page attempts,
etc, etc. This statement, along with the CHAT and PAGEOFF
statements and the PAGESTAT() function, allow you to implement
an operator page in any way desired. Note that this statement
will also update the current callers statistics PSA if it is
installed.
Examples
PAGEON
FOR i = 1 TO 10
PRINT "@BEEP@"
DELAY 18
IF (KINKEY() = " ") THEN
CHAT
GOTO exit
ENDIF
NEXT
:exit
See Also
CHAT Statement, PAGEOFF Statement, PAGESTAT() Function
PAGESTAT() Function
Function
Determine if the current user has paged the SysOp.
Syntax
PAGESTAT()
No arguments are required
Return Type and Value
BOOLEAN Returns TRUE if the user has paged the SysOp, FALSE
otherwise.
Remarks
One of the features of PCBoard where change is often requested
is the operator page facility. Some people want to be able to
configure multiple ranges of availability per day, some want a
different sounding page bell, longer or shorter page attempts,
etc, etc. This function, along with the CHAT, PAGEON and
PAGEOFF statements, allow you to implement an operator page in
any way desired.
Examples
IF (PAGESTAT()) THEN
PRINTLN "You have already paged the SysOp,"
PRINTLN "please be patient."
ELSE
PAGEON
PRINTLN "The SysOp has been paged, continue"
ENDIF
See Also
CHAT Statement, PAGEOFF Statement, PAGEON Statement
PCBDAT() Function
Function
Return the path and file name of the PCBOARD.DAT file.
Syntax
PCBDAT()
No arguments are required
Return Type & Value
STRING Returns the path and file name of the PCBOARD.DAT
file for the currnet node.
Remarks
The PCBOARD.DAT file is the master confiuration file for each
node running PCBoard. As such, there are many useful pieces of
information that can be obtained from it. It is a standard text
file with one piece of information per line. You may use the
READLINE() function to read individual pieces of information
from it.
Examples
STRING s
LET s = READLINE(PCBDAT(),1)
PRINTLN "PCBOARD.DAT version info - ",s
See Also
PCBNODE() Function
Function
Return the current node number.
Syntax
PCBNODE()
No arguments are required
Return Type & Value
INTEGER Returns the node number for the current node.
Remarks
You may have need to know what node is in use for certain
applications (for example, to create temporary files with unique
names or to restrict features to a particular node or nodes).
This function will return a number from 1 to the maximum number
of nodes allowed with a given copy of PCBoard. Note that the
node number may not be what is defined in PCBOARD.DAT if the
/FLOAT or /NODE switches are used.
Examples
STRING file
LET file = "TMP"+STRING(PCBNODE())+".$$$"
DELETE file
See Also
PEEKB() Function
Function
Return the value of a byte at a specified memory address.
Syntax
PEEKB(addr)
addr An integer expression with the address of the byte
to peek.
Return Type & Value
INTEGER Returns the value of the byte at addr.
Remarks
It is sometimes necessary to read values from memory directly
(for example, from the system BIOS data segment). This function
will return a byte quantity (0-255) from a specified memory
address.
Examples
PRINTLN "The current video mode is
",PEEKB(MKADDR(40h,49h))
See Also
MKADDR() Function, PEEKDW() Function, PEEKW() Function, POKEB()
Function, POKEDW() Function, POKEW() Function, VARADDR
Statement, VAROFF Statement, VARSEG Statement
PEEKDW() Function
Function
Return the value of a double word at a specified memory address.
Syntax
PEEKDW(addr)
addr An integer expression with the address of the double
word to peek.
Return Type & Value
INTEGER Returns the value of the double word at addr.
Remarks
It is sometimes necessary to read values from memory directly
(for example, from the system BIOS data segment). This function
will return a double word quantity as a signed integer (-
2,147,483,648 - +2,147,483,647) from a specified memory address.
Examples
PRINTLN "Timer ticks since midnight =
",PEEKDW(MKADDR(40h,6Ch))
See Also
MKADDR() Function, PEEKB() Function, PEEKW() Function, POKEB()
Function, POKEDW() Function, POKEW() Function, VARADDR
Statement, VAROFF Statement, VARSEG Statement
PEEKW() Function
Function
Return the value of a word at a specified memory address.
Syntax
PEEKW(addr)
addr An integer expression with the address of the word
to peek.
Return Type & Value
INTEGER Returns the value of the word at addr.
Remarks
It is sometimes necessary to read values from memory directly
(for example, from the system BIOS data segment). This function
will return a word quantity (0-65,535) from a specified memory
address.
Examples
PRINTLN "The usable memory size is
",PEEKW(MKADDR(40h,13h))
See Also
MKADDR() Function, PEEKB() Function, PEEKDW() Function, POKEB()
Function, POKEDW() Function, POKEW() Function, VARADDR
Statement, VAROFF Statement, VARSEG Statement
POKEB Statement
Function
Write a byte to a specified memory address.
Syntax
POKEB addr,value
addr An integer expression with the address to write to.
value An integer expression with the value to write
to addr.
Remarks
You may have need to write directly to memory from time to time.
This statement complements the PEEKB() function and allows you
to write a byte value (0-255) to a specific memory location.
Examples
BOOLEAN flag
INTEGER addr
VARADDR flag,addr
POKEB addr,TRUE ' Set the flag to TRUE the hard way
See Also
MKADDR() Function, PEEKB() Function, PEEKDW() Function, PEEKW()
Function, POKEDW() Function, POKEW() Function, VARADDR
Statement, VAROFF Statement, VARSEG Statement
POKEDW Statement
Function
Write a double word to a specified memory address.
Syntax
POKEDW addr,value
addr An integer expression with the address to write to.
value An integer expression with the value to write
to addr.
Remarks
You may have need to write directly to memory from time to time.
This statement complements the PEEKDW() function and allows you
to write a double word value (-2,147,483,648 - +2,147,483,647)
to a specific memory location.
Examples
MONEY amt
INTEGER addr
VARADDR amt,addr
POKEDW addr,123456 ' Set amt to $1234.56 the hard
way
See Also
MKADDR() Function, PEEKB() Function, PEEKDW() Function, PEEKW()
Function, POKEB() Function, POKEW() Function, VARADDR Statement,
VAROFF Statement, VARSEG Statement
POKEW Statement
Function
Write a word to a specified memory address.
Syntax
POKEW addr,value
addr An integer expression with the address to write to.
value An integer expression with the value to write
to addr.
Remarks
You may have need to write directly to memory from time to time.
This statement complements the PEEKW() function and allows you
to write a word value (0-65,535) to a specific memory location.
Examples
DATE dob
INTEGER addr
VARADDR dob,addr
POKEW addr,MKDATE(1967,10,31) ' Set dob the hard
way
See Also
MKADDR() Function, PEEKB() Function, PEEKDW() Function, PEEKW()
Function, POKEB() Function, POKEDW() Function, VARADDR
Statement, VAROFF Statement, VARSEG Statement
POP Statement
Function
Pop the results of one or more expressions from a stack.
Syntax
POP var[,var]
var A variable of any type in which to retrieve
previously pushed expression.
Remarks
This statement will retrieve the results of one or more
expressions of any type from a stack into a list of variables.
The values should have been previously pushed with the PUSH
statement. Together PUSH and POP can be used for parameter
passing, to create 'local' variables, or to reverse the order of
arguments.
Examples
INTEGER i, tc
STRING s
LET tc = TOKCOUNT()
WHILE (TOKCOUNT() > 0) PUSH GETTOKEN() ' push them
in order
FOR i = 1 TO tc
POP s ' pop them
in reverse
PRINTLN s
NEXT
INTEGER i
FOR i = 1 TO 10
PRINT i," - "
GOSUB sub
NEXT
END
:sub
PUSH i '
temporarily save i
LET i = i*i
PRINTLN i
POP i ' restore
saved i
RETURN
INTEGER v
PRINT "A cube with dimensions 2X3X4"
PUSH 2,3,4 ' pass
pushed parameters
GOSUB vol
POP v ' pop result
PRINTLN "has volume ",v
END
:vol
INTEGER w,h,d
POP d,h,w ' pop passed
parameter
PUSH w*h*d ' push
result
RETURN
See Also
PUSH Statement
PPENAME() Function
Function
Return the base name of an executing PPE file.
Syntax
PPENAME()
No arguments are required
Return Type & Value
STRING Returns the base file name (without path or
extension) of the currently executing PPE.
Remarks
This function will return the name of the PPE file that is
running. This can be useful when writing PPL applications that
will use data files that you would like to keep named the same
as the parent application regardless of what the PPE name may
change to.
Examples
STRING s
FOPEN 1,PPEPATH()+PPENAME()+".CFG",O_RD,S_DN
FGET 1,s
FCLOSE 1
See Also
PPEPATH() Function
PPEPATH() Function
Function
Return the path of an executing PPE file.
Syntax
PPEPATH()
No arguments are required
Return Type & Value
STRING Returns the path (without file name or extension) of
the currently executing PPE.
Remarks
This function will return the path of the PPE file that is
running. This can be useful when writing PPL applications that
will use files that you would like to keep in the same location
as the parent application regardless of where the PPE may be
installed.
Examples
STRING s
FOPEN 1,PPEPATH()+PPENAME()+".CFG",O_RD,S_DN
FGET 1,s
FCLOSE 1
See Also
PPENAME() Function
PRINT/PRINTLN Statements
Function
Print (write) a line to the screen (with an optional newline
appended).
Syntax
P R I N T e x p [ , e x p ]
- o r -
PRINTLN [exp[,exp]]
exp An expression of any type to evaluate and write to
the screen.
Remarks
These statements will evalutate zero, one or more expressions of
any type and write the results to the display. The PRINTLN
statement will append a newline to the end of the expressions;
PRINT will not. Note that at least one expression must be
specified for PRINT, unlike the PRINTLN statement which need not
have any arguments passed to it. Finally, both statements will
process all @ codes and display them as expected.
Examples
PRINT "The name of the currently running PPE file
is "
PRINTLN PPENAME(),"."
PRINT "The path where it is located is "
PRINTLN PPEPATH(),"."
PRINT "The date is ",DATE()," and the time is
",TIME(),"."
PRINTLN
PRINT "@X1FThis is bright white on blue..."
PRINTLN "how do you like it @FIRST@"
See Also
MPRINT/MPRINTLN Statements, SPRINT/SPRINTLN Statements
PROMPTSTR Statement
Function
Prompt the user for a string of text in a specific format.
Syntax
PROMPTSTR prompt,var,len,valid,flags
prompt An integer expression with the prompt number
from PCBTEXT to display to the user.
var The variable in which to store the user's input.
len An integer expression with maximum length of text to
input.
valid A string expression with the valid characters
that the user may enter.
flags An integer expression with flags to modify how
the statement works.
Remarks
This statement will accept a string of input from the user, up
to the length defined. The prompt parameter will be used to
find the prompt from PCBTEXT (which includes the prompt color)
to display to the user. Only characters found in the valid
parameter will be accepted. However, the flags parameter may
affect how prompt is displayed and the valid characters that are
accepted. Individual flags may be added together as needed.
Several functions exist to easily specify commonly used valid
character masks. They are MASK_ALNUM(), MASK_ALPHA(),
MASK_ASCII(), MASK_FILE(), MASK_NUM(), MASK_PATH(), and
MASK_PWD(). Defined flag values are AUTO, DEFS, ECHODOTS,
ERASELINE, FIELDLEN, GUIDE, HIGHASCII, LFAFTER, LFBEFORE,
NEWLINE, NOCLEAR, STACKED, UPCASE, WORDWRAP, and YESNO.
Examples
BOOLEAN b
DATE d
INTEGER i
MONEY m
STRING s
TIME t
' NOTE: prompt 706 is used here for all
statements;
' you may use any prompt you wish
PROMPTSTR 706,b,1,"10",LFBEFORE+NEWLINE
PROMPTSTR 706,d,8,"0123456789-",NEWLINE+NOCLEAR
PROMPTSTR 706,i,20,MASK_NUM(),NEWLINE
PROMPTSTR
706,m,9,MASK_NUM()+".",NEWLINE+DEFS+FIELDLEN
PROMPTSTR
706,s,63,MASK_ASCII(),NEWLINE+FIELDLEN+GUIDE
PROMPTSTR 706,t,5,"0123456789"+":",NEWLINE+LFAFTER
PRINTLN b," ",d," ",i
PRINTLN m," ",s," ",t
See Also
INPUT Statement, INPUT... Statement, INPUTSTR Statement,
INPUTTEXT Statement
PSA() Function
Function
Determine whether or not a given PSA is installed.
Syntax
PSA(num)
num An integer expression with the number of the PSA to
check for the existence of.
Return Type & Value
BOOLEAN Returns TRUE if the specified PSA exists or FALSE if
it doesn't exist for the following values of num:
1 The Alias PSA;
2 The Verification PSA.
3 The Address PSA;
4 The Password PSA;
5 The Statistics PSA.
6 The Notes PSA.
Remarks
This function allows you to determine whether or not a given
PCBoard Supported Allocation (PSA) is installed. For each of
the six PSAs it will return TRUE if installed or FALSE if not
installed. It is useful when you want to write a generic PPL
application that will access one or more PSAs that may or may
not be installed.
Examples
STRING ynStr(1)
LET ynStr(0) = "NO"
LET ynStr(1) = "YES"
PRINTLN " Alias Support Enabled?
",ynStr(PSA(1))
PRINTLN "Verification Support Enabled?
",ynStr(PSA(2))
PRINTLN " Address Support Enabled?
",ynStr(PSA(3))
PRINTLN " Password Support Enabled?
",ynStr(PSA(4))
PRINTLN " Statistics Support Enabled?
",ynStr(PSA(5))
PRINTLN " Notes Support Enabled?
",ynStr(PSA(6))
See Also
PUSH Statement
Function
Push (save) the results of one or more expressions on a stack.
Syntax
PUSH exp[,exp]
exp An expression of any type to evaluate and push.
Remarks
This statement will evalutate one or more expressions of any
type and push the results onto a stack for temporary storage.
The results of those expressions may be retrieved via the POP
statement. Together PUSH and POP can be used for parameter
passing, to create 'local' variables, or to reverse the order of
arguments.
Examples
INTEGER i, tc
STRING s
LET tc = TOKCOUNT()
WHILE (TOKCOUNT() > 0) PUSH GETTOKEN() ' push them
in order
FOR i = 1 TO tc
POP s ' pop them
in reverse
PRINTLN s
NEXT
INTEGER i
FOR i = 1 TO 10
PRINT i," - "
GOSUB sub
NEXT
END
:sub
PUSH i '
temporarily save i
LET i = i*i
PRINTLN i
POP i ' restore
saved i
RETURN
INTEGER v
PRINT "A cube with dimensions 2X3X4"
PUSH 2,3,4 ' pass
pushed parameters
GOSUB vol
POP v ' pop result
PRINTLN "has volume ",v
END
:vol
INTEGER w,h,d
POP d,h,w ' pop passed
parameter
PUSH w*h*d ' push
result
RETURN
See Also
POP Statement
PUTUSER Statement
Function
Copy values from predeclared variables to user record.
Syntax
PUTUSER
No arguments are required
Remarks
There are many predeclared variables which may be used to access
and change user information. However, their values are
undefined until you use the GETUSER statement, and any changes
you make don't take hold until you use the PUTUSER statement.
Examples
IF (PSA(3)) THEN
GETUSER
INPUT "Addr 1",U_ADDR(0)
INPUT "Addr 2",U_ADDR(1)
INPUT "City ",U_ADDR(2)
INPUT "State ",U_ADDR(3)
INPUT "ZIP ",U_ADDR(4)
INPUT "Cntry ",U_ADDR(5)
PUTUSER
ENDIF
See Also
GETUSER Statement
QUEST Statement
Function
Allow the user to answer a specified script questionnaire.
Syntax
QUEST scrnum
scrnum The number of the script for the user to
answer. Valid values are 1 through the number of script
questionnaires available.
Remarks
This statement will present the user a specified script
questionnaire number to answer. The SCR.LST file for the
current conference will be searched for the script. If the
questionnaire number is invalid (less than 1 or greater than the
highest script number defined) then nothing will be displayed.
Examples
INTEGER num
INPUT "Script to answer",num
QUEST num
See Also
RANDOM() Function
Function
Return a random value between 0 and a specified limit.
Syntax
RANDOM(limit)
limit An integer expression with the maximum random
value desired.
Return Type & Value
INTEGER Returns the random number in the range 0 to limit.
Remarks
Random numbers have many applications from statistics to video
games. This function allows you to generate pseudo-random
numbers in the range 0 to limit inclusive.
Examples
INTEGER x,y
WHILE (KINKEY() <> " ") DO
CLS
LET x = 1+RANDOM(50)
LET y = 1+RANDOM(22)
COLOR 1+RANDOM(14)
ANSIPOS x,y
PRINT "Hit the SPACE BAR to continue"
DELAY 18
ANSIPOS x,y
CLREOL
ENDWHILE
See Also
RDUNET Statement
Function
Read information from the USERNET file for a specific node.
Syntax
RDUNET node
node An integer expression with the node to read.
Remarks
To facilitate internode communications, a file named USERNET.XXX
is maintained with an entry for each node on the system. This
file is used by the BROADCAST command of PCBoard and to prevent
multiple simultaneous logins, among other things. This
statement may be used to read information for any node.
Examples
RDUNET PCBNODE()
WRUNET
PCBNODE(),UN_STAT(),UN_NAME(),UN_CITY(),"Running
"+PPENAME(),""
RDUNET 1
WRUNET
1,UN_STAT(),UN_NAME(),UN_CITY(),UN_OPER(),"Hello
there node 1"
See Also
UN_...() Function, RDUNET Statement
RDUSYS Statement
Function
Read a USERS.SYS file in from disk.
Syntax
RDUSYS
No arguments are required
Remarks
Some DOOR applications require a USERS.SYS file to access
information about the caller. This statement allows you to read
the USERS.SYS file back into memory in case any changes were
made by the DOOR during the SHELL statement. This statement
should only be used after a SHELL statement that was preceeded
by a WRUSYS statement.
Examples
INTEGER ret
WRUSYS
SHELL FALSE,ret,"MYAPP.EXE",""
RDUSYS
See Also
WRUSYS Statement
READLINE() Function
Function
Read a specific line number from a text file.
Syntax
READLINE(file,line)
file A string expression with the file name to read from.
line An integer expression with the line number to read.
Return Type & Value
STRING Returns the specified line number from file.
Remarks
It is often convienient to read a specified line number from a
file without going to all the overhead of opening, reading and
closing. This function will open the file in read mode for
share deny none access and quickly read up to the line number
you specify. If the line you want doesn't exist an empty string
will be returned. Additionally, this function will remember the
last file and line read so that it may quickly continue where it
left off if you try to read a number of lines sequentially from
the same file. Finally, the last file specified will remain
open until the PPE exits and returns control to PCBoard.
Examples
PRINTLN "This system is running on IRQ
",READLINE(PCBDAT(),158)
PRINTLN "with a base IO address of
",READLINE(PCBDAT(),159)
See Also
REG...() Functions
Function
Get the value of a register.
Syntax
REG...()
No arguments are required
REG should be followed by one of the following register names:
AH, AL, AX, BH, BL, BX, CF, CH, CL, CX, DH, DI, DL, DS, DX, ES,
F or SI.
Return Type & Value
BOOLEAN (REGCF() only) Returns TRUE if the carry flag is
set, FALSE otherwise.
INTEGER (All others) Returns the value in the specified
register.
Remarks
There are actually 18 different functions that return the values
of registers. AL, AH, BL, BH, CL, CH, DL, and DH will always
return byte sized values (0-255). AX, BX, CX, DX, DI, SI, DS,
and ES will always return word sized values (0-65535). F
(flags) returns the settings for the various 80x86 processor
flags. CF is a subset of F in that it only returns the status
of the carry flag. It exists because the carry flag is often
used to report success or failure in assembly language. The
REGF() function returns the settings for the following flags:
Carry, Parity, Auxilliary, Zero, Sign, Trap, Interrupt,
Direction, and Overflow. Their bit positions are as follows:
O D I T S Z - A - P - C
80 40 20 10 08 04 02 01 00 00 00 00
0h 0h 0h 0h 0h 0h 0h 0h 8h 4h 2h 1h
Examples
' Create subdirectory - DOS function 39h
INTEGER addr
STRING path
LET path = "C:\$TMPDIR$"
VARADDR path,addr
DOINTR
21h,39h,0,0,addr%00010000h,0,0,0,addr/00010000h,0
IF (REGCF() & (REGAX() = 3)) THEN
PRINTLN "Error: Path not found"
ELSE IF (REGCF() & (REGAX() = 5)) THEN
PRINTLN "Error: Access Denied"
ELSE IF (REGCF()) THEN
PRINTLN "Error: Unknown Error"
ELSE
PRINTLN "Directory successfully created..."
ENDIF
See Also
B2W() Function, DOINTR Statement, VARADDR Statement, VAROFF
Statement, VARSEG Statement
RENAME Statement
Function
Rename (or move) a file.
Syntax
RENAME old,new
old A string expression with the old path and/or file
name.
new A string expression with the new path and/or file
name.
Remarks
Similar to how the RENAME command works from the DOS prompt,
this statement will take a file and give it a new name. Unlike
the RENAME command, the RENAME statement will not accept
wildcards in the old or new parameters. Also, it doesn't
require that the old path and the new path be the same (the
drive letters must match, but the paths need not), so it may be
used to move files from one location to another on a single
drive. So, you could use it to move a file from C:\PCB\NODE1 to
C:\PCB\NODE2 (renaming it at the same time if you wish), but you
couldn't use it to move a file from C:\PCB\NODE1 to
D:\WORK\NODE1.
Examples
' Swap the PCBOARD DAT & NXT files
RENAME "PCBOARD.DAT","PCBOARD.TMP"
RENAME "PCBOARD.NXT","PCBOARD.DAT"
RENAME "PCBOARD.TMP","PCBOARD.NXT"
' Move the file to the backup directory
RENAME
"PPE.LOG","LOGBAK\"+I2S(DATE()*86400+TIME(),36)
See Also
REPLACE() Function
Function
Change all occurences of a given character to another character
in a string.
Syntax
REPLACE(str,old,new)
str Any string expression.
old A string expression with the old character to be
replaced.
new A string expression with the new character to
replace with.
Return Type & Value
STRING Returns str with all occurences of old changed to
new.
Remarks
This function will search a string for a given character and
replace all instances of that character with another character.
This can be useful in many scenarios, especially when formatting
text for display purposes.
Examples
PRINTLN "Your internet address on this system is:"
PRINTLN REPLACE(LOWER(U_NAME()),"
","."),"@clarkdev.com"
See Also
RESETDISP Statement
Function
Reset the display to allow more information after an abort.
Syntax
RESETDISP
No arguments are required
Remarks
PCBoard normally automatically counts lines and, if enabled,
pauses the display after every screenful. The user may (unless
disabled) abort the display at any MORE? prompt or with the
^K/^X keys. If this happens no further information will be
displayed until you use the RESETDISP statement. You can check
to see if RESETDISP is necessary (ie, has the user aborted the
display) with the ABORT() function.
Examples
INTEGER I
STARTDISP FCL
' While the user has not aborted, continue
WHILE (!ABORT()) DO
PRINTLN "I is equal to ",I
INC I
ENDWHILE
RESETDISP
See Also
ABORT() Function, STARTDISP Statement
RESTSCRN Statement
Function
Restore the screen from a previously saved buffer.
Syntax
RESTSCRN
No arguments are required
Remark
PCBoard will save and restore the screen before and after
certain functions, such as SysOp chat. This allows the user to
continue right where he left off without having to remember what
was on the screen before being interrupted. You can add that
same functionality with the SAVESCRN and RESTSCRN statements.
The SAVESCRN statement allocates memory for a buffer in which to
save the screen. If the SAVESCRN statement isn't followed by a
RESTSCRN statement then that memory will never be deallocated.
Finally, this statement will work regardless of ANSI
availability; the screen is only saved up to the position of the
cursor and this statement assumes that it can safely restore the
screen using standard teletype conventions to just scroll the
data onto the display.
Examples
SAVESCRN
CLS
PRINTLN "We interrupt your regular BBS session"
PRINTLN "with this important message:"
NEWLINE
PRINTLN "A subscription to this system only costs
$5!"
PRINTLN "Subscribe today!"
NEWLINES 2
WAIT
RESTSCRN
See Also
SAVESCRN Statement
RETURN Statement
Function
Transfer program control back to a previously saved address.
Syntax
RETURN
No arguments are required
Remarks
It is often necessary to perform an indentical set of
instructions several times in a program. This leaves you with
two choices. One, rewrite the code several times (and hope you
do it right each time), or two, write it once as a subroutine,
then use GOSUB to run it. This statement will save the address
of the next line so that a RETURN statement at the end of the
subroutine can instruct PPL to resume execution with the line
following the GOSUB.
Examples
STRING Question, Answer
LET Question = "What is your street address ..."
GOSUB ask
LET Question = "What is your city, state and zip
..."
GOSUB ask
END
:ask ' Sub to ask a question, get an answer, and
log them to a file
LET Answer = ""
PRINTLN "@X0E",Question
INPUT "",Answer
NEWLINES 2
FPUTLN 0,"Q: ",STRIPATX(Question)
FPUTLN 0,"A: ",Answer
RETURN
See Also
END Statement, GOSUB Statement, GOTO Statement, STOP Statement
RIGHT() Function
Function
Access the right most characters from a string.
Syntax
RIGHT(str,chars)
str A string expression to take the right most
characters of.
chars An integer expression with the number of
characters to take from the right end of str.
Return Type & Value
STRING Returns a string with the right most chars
characters of str.
Remarks
This function will return a sub string with the right most chars
characters of a specified string. This can be useful in data
processing as well as text formatting. If chars is less than or
equal to 0 then the returned string will be empty. If chars is
greater than the length of str then the returned string will
have spaces added to the right to pad it out to the full length
specified.
Examples
WHILE (RANDOM(250) <> 0) PRINT
RIGHT(RANDOM(250),4)," "
STRING s
FOPEN 1,"DATA.TXT",O_RD,S_DN
WHILE (!FERR(1)) DO
FGET 1,s
PRINT RTRIM(LEFT(s,25)," ")," - "
PRINTLN RIGHT(s,LEN(s)-25)
ENDWHILE
FCLOSE 1
See Also
LEFT() Function, MID() Function
RTRIM() Function
Function
Trim a specified character from the right end of a string.
Syntax
RTRIM(str,ch)
str Any string expression.
ch A string with the character to strip from the right
end of str.
Return Type & Value
STRING Returns the trimmed str.
Remarks
A common need in programming is to strip leading and/or trailing
spaces (or other characters). This function will strip a
specified character from the right end of a string and return
the trimmed string.
Examples
STRING s
LET s = " TEST "
PRINTLN RTRIM(s," ") ' Will print " TEST"
PRINTLN RTRIM(".....DA"+"TA.....",".") ' Will print
".....DATA"
PRINTLN RTRIM(".....DA"+"TA....."," ") ' Will print
".....DATA....."
See Also
LTRIM() Function, TRIM() Function
S2I() Function
Function
Convert a string in a specified number base to an integer.
Syntax
S2I(str,base)
str Any string expression to convert to integer format.
base An integer expression with the number base (2
through 36) to convert from.
Return Type & Value
INTEGER Returns str converted from the specified number base
to an integer.
Remarks
People work with decimal (base 10) numbers, whereas computers
work with binary (base 2) numbers. It is often more convienient
to store or input numbers in a format other than decimal for
clarity, compactness, or other reasons. This function will
convert a string in any number base from 2 to 36 to a number.
So, S2I("1010",2) would return a 10; S2I("Z",36) would return
35. For more information on number bases, consult .
Examples
INTEGER i
STRING s
INPUTTEXT "Enter a string (any base)",s,@X0E,40
FOR i = 2 TO 36
PRINTLN s," = ",S2I(s,i)," base ",i
NEXT
See Also
I2S() Function
SAVESCRN Statement
Function
Save the screen to a buffer for later restoration.
Syntax
SAVESCRN
No arguments are required
Remark
PCBoard will save and restore the screen before and after
certain functions, such as SysOp chat. This allows the user to
continue right where he left off without having to remember what
was on the screen before being interrupted. You can add that
same functionality with the SAVESCRN and RESTSCRN statements.
The SAVESCRN statement allocates memory for a buffer in which to
save the screen. If the SAVESCRN statement isn't followed by a
RESTSCRN statement then that memory will never be deallocated.
Finally, this statement will work regardless of ANSI
availability; this statement will only save the screen up to the
position of the cursor. It is assumed that the screen can be
safely restored using standard teletype conventions to just
scroll the data onto the display.
Examples
SAVESCRN
CLS
PRINTLN "We interrupt your regular BBS session"
PRINTLN "with this important message:"
NEWLINE
PRINTLN "A subscription to this system only costs
$5!"
PRINTLN "Subscribe today!"
NEWLINES 2
WAIT
RESTSCRN
See Also
RESTSCRN Statement
SCRTEXT() Function
Function
Access text and attribute information directly from BBS screen
memory.
Syntax
SCRTEXT(x,y,len,color)
x An integer expression with the x coordinate (column)
from which to read screen memory.
y An integer expression with the y coordinate (row)
from which to read screen memory.
len An integer expression with the length, in columns,
of the string to read from screen memory.
color A boolean expression with TRUE if color
information should be included, FALSE otherwise.
Return Type & Value
STRING Returns the specified region of screen memory.
Remarks
This function is useful for temporarily saving a portion of
screen memory, with or without color information. If the color
parameter is set to TRUE color information will be included in
the form of @X codes embedded in the text. Note that the
maximum length of a string is 256 characters; however, a row of
80 characters could be as long as 400 characters (4 bytes for
the @X code and 1 byte for the character itself). You should
generally limit yourself to a length of 51 characters or less if
you want to include color information unless you are certain
that attribute changes will not exceed the 256 character string
limit.
Examples
' scroll the screen to the left 5 columns and down
3 rows
INTEGER r
STRING s
FOR r = 20 TO 1 STEP -1
LET s = SCRTEXT(6,r,75,TRUE)
ANSIPOS 1,r+3
CLREOL
PRINT s
NEXT
FOR r = 1 TO 3
ANSIPOS 1,r
CLREOL
NEXT
See Also
SEC Constant
Function
Set the security level specific file search flag in a DISPFILE
statement.
Value
2 = 10b = 2o = 2h
Remarks
The DISPFILE statement will allow you to display a file to the
user, and optionally to have PCBoard look for alternate
security, graphics, and/or language specific files. This flag
instructs PCBoard to search for alternate security level files
via the security level suffix. The current security level may
be obtained with the CURSEC() function.
Examples
STRING s
DISPFILE "MNUA",SEC+GRAPH+LANG
INPUT "Option",s
See Also
CURSEC() Function, DISPFILE Statement, GRAPH Constant, LANG
Constant
SEC() Function
Function
Extract the second of the minute from a specified time of day.
Syntax
SEC(texp)
texp Any time expression.
Return Type & Value
INTEGER Returns the second of the minute from the specified
time expression (texp). Valid return values are from 0 to 59.
Remarks
This function allows you to extract a particular piece of
information about a TIME value, in this case the second of the
minute of the time of day expression.
Examples
PRINTLN "The minute is ",SEC(TIME())
See Also
HOUR() Function, MIN() Function
SENDMODEM Statement
Function
Send a string to the modem.
Syntax
SENDMODEM str
str A string expression to send to the modem.
Remarks
The primary use of this statement is to send commands to a modem
when no one is online. For example, you would use this to send
a dial command to the modem in a call back PPL application.
However, it is not restricted to sending commands. Note that
modem commands must be terminated by a carriage return and that
this statement will not automatically do it for you. This
allows you to send a command to the modem is several stages and
only terminate the final stage with a carriage return.
Examples
BOOLEAN flag
CDCHKOFF
KBDCHKOFF
DTROFF
DELAY 18
DTRON
SENDMODEM "ATDT"
SENDMODEM "5551212"
SENDMODEM CHR(13)
WAITFOR "CONNECT",flag,60
IF (!flag) LOG "No CONNECT after 60 seconds",FALSE
KBDCHKON
CDCHKON
See Also
SHELL Statement
Function
Shell out to a program or batch file.
Syntax
SHELL viacc,retcode,prog,cmds
viacc A boolean expression with value TRUE if the
shell should be made via COMMAND.COM; FALSE if it should be
shelled to directly.
retcode A variable in which to store the return code.
prog A string expression with the file name to shell to.
cmds A string expression with any arguments to pass to
prog.
Remarks
You may have have need to run a COM, EXE or BAT file from your
PPE. You may need to do this to simulate running a DOOR or to
access some service not normally available from PCBoard or PPL.
This function will allow you to do that. If the viacc parameter
is TRUE (you want COMMAND.COM to load the specified file) then
your PATH environment variable will be searched for prog if it
isn't in the current directory or isn't fully qualified (path
and extension) as though you had entered it on the command line.
If viacc is FALSE then you must specify the path and extension
of the program to run. Additionally, the retcode variable will
only be meaningful if viacc is FALSE.
Examples
INTEGER rc
SHELL TRUE,rc,"DOOR",""
INTEGER rc
STRING p,c
LET p = "DOORWAY.EXE"
LET c = "com2 /v:d^O /m:600 /g:on /o: /k:v0 /x:
/c:dos"
SHELL FALSE,rc,p,c
See Also
SHOWOFF Statement
Function
Turn off showing information to the display.
Syntax
SHOWOFF
No arguments are required
Remark
This statement allows your PPL application to turn off writing
information to the local and remote displays. Used in
conjunction with the SHOWSTAT() function and the OPENCAP,
CLOSECAP, and SHOWON statements it allows you to temporarily
turn off the display while capturing output to the screen. This
can be useful anytime you want to automate a feature for the
user and allow them to download the resulting capture file
instead of spending lots of time online.
Examples
BOOLEAN ss
LET ss = SHOWSTAT()
SHOWOFF
OPENCAP "CAP"+STRING(PCBNODE()),ocFlag
IF (ocFlag) THEN
DIR "U;NS"
CLOSECAP
KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13)
ENDIF
IF (ss) THEN
SHOWON
ELSE
SHOWOFF
ENDIF
See Also
CLOSECAP Statement, OPENCAP Statement, SHOWON Statement,
SHOWSTAT() Function
SHOWON Statement
Function
Turn on showing information to the display.
Syntax
SHOWON
No arguments are required
Remark
This statement allows your PPL application to turn on writing
information to the local and remote displays. Used in
conjunction with the SHOWSTAT() function and the OPENCAP,
CLOSECAP, and SHOWOFF statements it allows you to temporarily
turn off the display while capturing output to the screen. This
can be useful anytime you want to automate a feature for the
user and allow them to download the resulting capture file
instead of spending lots of time online.
Examples
BOOLEAN ss
LET ss = SHOWSTAT()
SHOWOFF
OPENCAP "CAP"+STRING(PCBNODE()),ocFlag
IF (ocFlag) THEN
DIR "U;NS"
CLOSECAP
KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13)
ENDIF
IF (ss) THEN
SHOWON
ELSE
SHOWOFF
ENDIF
See Also
CLOSECAP Statement, OPENCAP Statement, SHOWOFF Statement,
SHOWSTAT() Function
SHOWSTAT() Function
Function
Determine if data is being shown on the display.
Syntax
SHOWSTAT()
No arguments are required
Return Type and Value
BOOLEAN Returns TRUE if data is being shown on the display,
FALSE otherwise.
Remarks
This function allows your PPL application to determine the
status of writing information to the local and remote displays.
Used in conjunction with the OPENCAP, CLOSECAP, SHOWON, and
SHOWOFF statements it allows you to temporarily turn off the
display while capturing output to the screen. This can be
useful anytime you want to automate a feature for the user and
allow them to download the resulting capture file instead of
spending lots of time online.
Examples
BOOLEAN ss
LET ss = SHOWSTAT()
SHOWOFF
OPENCAP "CAP"+STRING(PCBNODE()),ocFlag
IF (ocFlag) THEN
DIR "U;NS"
CLOSECAP
KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13)
ENDIF
IF (ss) THEN
SHOWON
ELSE
SHOWOFF
ENDIF
See Also
CLOSECAP Statement, OPENCAP Statement, SHOWOFF Statement, SHOWON
Statement
SLPATH() Function
Function
Return the path of login security files as defined in PCBSetup.
Syntax
SLPATH()
No arguments are required
Return Type & Value
STRING Returns the path of the PCBoard login security
files.
Remarks
This function will return the path where login security files
are located as defined in PCBSetup. It can be used to create
and change them on the fly.
Examples
FAPPEND 1,SLPATH()+STRING(CURSEC),O_WR,S_DB
FPUTLN 1,U_NAME()
FCLOSE 1
See Also
SOUND Statement
Function
Turn on the speaker on the local computer at a specific
frequency.
Syntax
SOUND freq
freq An integer expression with the frequency (in hertz)
at which to turn on the speaker or 0 to turn off the speaker.
Remarks
This statement can be used to generate just about any tone
desired on the speaker on the local PC. It has no effect on the
remote computer and will only work with the built in speaker (in
other words, it has no way of communicating with advanced sound
cards). You specify the frequency of the tone you wish to
generate in hertz and pass it to the statement, or pass 0 to
turn off the speaker.
Examples
PAGEON
FOR i = 1 TO 10
MPRINT CHR(7)
SOUND 440
DELAY 9
SOUND 0
DELAY 9
IF (KINKEY() = " ") THEN
CHAT
GOTO exit
ENDIF
NEXT
:exit
See Also
SPACE() Function
Function
Create a string with a specified of spaces.
Syntax
SPACE(len)
len An integer expression with the number of spaces for
the new string.
Return Type & Value
STRING Returns a string of len spaces.
Remarks
This function is useful when formatting screen displays without
ANSI and when writing formatted information out to a file. It
will create a string of the length specified with nothing but
spaces. The returned string may have anywhere from 0 to 256
spaces.
Examples
PRINT
RANDOM(9),SPACE(5),RANDOM(9),SPACE(5),RANDOM(9)
FCREATE 1,"NEWFILE.DAT",O_WR,S_DB
FPUTLN 1,"NAME",SPACE(24),"CITY",SPACE(23),"PHONE"
FCLOSE 1
See Also
SPRINT/SPRINTLN Statements
Function
Print (write) a line to the local screen (BBS) only (with an
optional newline appended).
Syntax
S P R I N Te x p [ , e x p ]
- o r -
SPRINTLN [exp[,exp]]
exp An expression of any type to evaluate and write to
the caller's screen.
Remarks
These statements will evalutate zero, one or more expressions of
any type and write the results to the BBS for the SysOp's
display. The SPRINTLN statement will append a newline to the
end of the expressions; SPRINT will not. Note that at least one
expression must be specified for SPRINT, unlike the SPRINTLN
statement which need not have any arguments passed to it. These
statements only send information to the local display and do not
interpret @ codes; however, complete ANSI sequences will be
interpreted.
Examples
SPRINT "The name of the currently running PPE file
is "
SPRINTLN PPENAME(),"."
SPRINT "The path where it is located is "
SPRINTLN PPEPATH(),"."
SPRINT "The date is ",DATE()," and the time is
",TIME(),"."
SPRINTLN
See Also
MPRINT/MPRINTLN Statements, PRINT/PRINTLN Statements
STACKED Constant
Function
Set the allow stacked commands flag in an INPUTSTR or PROMPTSTR
statement.
Value
16 = 10000b = 20o = 10h
Remarks
The INPUTSTR and PROMPTSTR statements have the ability to allow
space and semi-colon characters to be input independent of the
valid character string specified. This facilitates entering
stacked commands (commands separated by space or semi-colon
delimiters) by only requiring a single value be set in the input
statement instead of having to add " ;" to every valid character
mask.
Examples
STRING cmds
INPUTSTR
"Commands",cmds,@X0E,60,MASK_ASCII(),STACKED
TOKENIZE cmds
LET cmds = GETTOKEN()
IF (cmds = "QUIT") END
KBDSTUFF cmds+TOKENSTR()
See Also
INPUTSTR Statement, PROMPTSTR Statement
STARTDISP Statement
Function
Start PCBoard's display routines in a specified mode.
Syntax
STARTDISP mode
mode An integer expression with the mode for display.
Remarks
PCBoard has two modes for displaying information: non stop and
line count. Non stop mode (initiated by passing FNS, for Force
Non Stop, as the mode parameter) displays information without
regard to how fast the display is or whether or not the user can
read it all. Line count mode (initiated by passing FCL, for
Force Count Lines, as the mode parameter) displays information
while counting lines and pausing after every screenful to wait
for user input. Finally, NC may be specified to reinitialize
the internal display counters without changing the current mode.
Examples
STARTDISP FCL
FOR i = 1 TO 100
PRINTLN "Line ",i
NEXT
STARTDISP FNS
FOR i = 1 TO 100
PRINTLN "Line ",i
NEXT
STARTDISP NC
FOR i = 1 TO 100
PRINTLN "Line ",i
NEXT
See Also
ABORT() Function, RESETDISP Statement
STOP Statement
Function
Abort PPE execution.
Syntax
STOP
No arguments are required
Remarks
This statement may be used to abnormally terminate PPE execution
at any point. The only real difference between this statement
and END is whether or not information written to channel 0 is
saved when the . END will save the output to the script answer
file; STOP will not.
Examples
STRING Question, Answer
LET Question = "What is your street address ..."
GOSUB ask
INPUTYN "Save address",Answer,@X0E
IF (Answer = NOCHAR()) STOP
END
:ask ' Sub to ask a question, get an answer, and
log them to a file
LET Answer = ""
PRINTLN "@X0E",Question
INPUT "",Answer
NEWLINES 2
FPUTLN 0,"Q: ",STRIPATX(Question)
FPUTLN 0,"A: ",Answer
RETURN
See Also
END Statement, RETURN Statement
STRING Type
Function
Declare one or more variables of type string.
Syntax
STRING var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])]
var The name of a variable to declare. Must start with
a letter [A-Z] which may be followed by letters, digits [0-9] or
the underscore [_]. May be of any length but only the first 32
characters are used.
arr The name of an array variable to declare. The same
naming conventions as var are used.
s The size (0-based) of an array variable dimension.
Any constant integer expression is allowed.
Remarks
STRING variables are stored as pointers arrays of characters
from 0 to 257 bytes in size. If the array has 0 or 1 characters
in it, it is a 0 length string. Arrays with 2 to 257 characters
have a length of the array size minus one. Valid string
characters are ASCII 1 through ASCII 255. ASCII 0 is reserved
for terminating the string and may not appear in the middle of
the string. A STRING assignment to an INTEGER will convert the
string to the four byte binary integer value (similar to BASIC's
VAL function and C's atol function). An INTEGER to STRING
assignment will result in a string with the representation of
the number (similar to BASIC's STR$ function and C's ltoa
function). If a STRING is assigned to or from any other type,
an appropriate conversion is performed automatically by PPL.
Examples
STRING char, str, tmp, labels(10), names(20,3)
See Also
BOOLEAN Type, DATE Type, INTEGER Type, MONEY Type, TIME Type
STRING() Function
Function
Convert any expression to a string.
Syntax
STRING(exp)
exp Any expression.
Return Type & Value
STRING Returns exp formatted as a string.
Remarks
This function is immensely useful anytime you need to convert
any expression to string format. For example, to append an
integer value to the end of a string without this function, you
would need to assign the integer to a string and then append the
temporary string to actual string. This is because PPL's normal
course of action when performing arithmetic with incompatible
types is to convert everything to integer first. With this
function, you can accomplish the same function in one line of
code with one expression because you are forcing addition of
compatible types (strings). Note that PPL does automatically
convert incompatible types whenever possible, making this
function unnecessary in many cases. This function should only
be necessary when trying to append the text representation of a
non-string type to a string via the + operator.
Examples
INTEGER i
STRING s(5)
FOR i = 1 to 5
LET s(i) = "This is string "+STRING(i)
NEXT
STRING s
LET s = STRING(ABORT())+" "+STRING(DATE())+"
"+STRING(10)+" "
LET s = s+STRING($10.00)+" "+STRING(TIME())
PRINTLN s ' will print "0 10-31-67 10 $10.00
03:27:00" (or similar)
See Also
STRIP() Function
Function
Remove all occurrences of a character from a string.
Syntax
STRIP(str,ch)
str Any string expression.
ch String with character to remove from str.
Return Type & Value
STRING Returns sexp without occurrences of ch that may have
been present previously.
Remarks
This function is used to strip a selected character from a
string. This can be useful when you need to remove known
formatting characters from a string, such as slashes and hyphens
from a date string.
Examples
STRING s
WHILE (LEN(s) < 6) DO
INPUTSTR "Enter date (MM-DD-
YY)",s,@X0E,8,"0123456789-",DEFS
LET s = STRIP(s,"-")
ENDWHILE
PRINTLN "Date (MMDDYY): ",s
See Also
STRIPATX() Function
Function
Remove @X codes from a string.
Syntax
STRIPATX(sexp)
sexp Any string expression.
Return Type & Value
STRING Returns sexp without any @X codes that may have been
present previously.
Remarks
This function is used to strip PCBoard @X color codes from a
string or string expression. This is useful when you want to
log information to a file without the @X codes used in the
screen display.
Examples
STRING Question, Answer
LET Question = "What is your street address ..."
GOSUB ask
END
:ask ' Sub to ask a question, get an answer, and
log them to a file
LET Answer = ""
PRINTLN "@X0E",Question
INPUT "",Answer
NEWLINES 2
FPUTLN 0,"Q: ",STRIPATX(Question)
FPUTLN 0,"A: ",Answer
RETURN
See Also
SYSOPSEC() Function
Function
Get the security level as the SysOp security level.
Syntax
SYSOPSEC()
No arguments are required
Return Type & Value
INTEGER Returns the SysOp security level as defined in
PCBSetup.
Remarks
This function is useful for those occasions when you need to
limit functionality in your PPL applications to users having a
security level greater than or equal to the defined SysOp
security level in PCBSetup.
Examples
INTEGER min
IF (CURSEC() >= SYSOPSEC()) THEN
LET min = 60
ELSE
LET min = 5
ENDIF
ADJTIME min
PRINTLN "Your time available has been increased by
",min," minutes"
See Also
S_DB Constant
Function
Set the share deny both (read and write) flag in a
FCREATE/FOPEN/FAPPEND statement.
Value
3 = 11b = 3o = 3h
Remarks
DOS 3.1 or later (which is what is required by PCBoard) allows
processes to decide what mode of file sharing should be allowed.
This constant allows you to specify that other processes may not
open the same file for either read or write access from the time
you open the file to the time you close the file. This is
useful when you need exclusive access to a file for any reason
and need to restrict other processes access to the same file.
Examples
FOPEN 1,"FILE.DAT",O_RD,S_DB ' Deny other processes
all access
FOR i = 1 TO 10
FGET 1,s
PRINTLN s
NEXT
FCLOSE 1 ' Close the file and allow others to open
it in any mode
See Also
S_DN Constant, S_DR Constant, S_DW Constant
S_DN Constant
Function
Set the share deny none flag in a FCREATE/FOPEN/FAPPEND
statement.
Value
0 = 0b = 0o = 0h
Remarks
DOS 3.1 or later (which is what is required by PCBoard) allows
processes to decide what mode of file sharing should be allowed.
This constant allows you to specify that other processes may
open the same file for read or write access from the time you
open the file to the time you close the file. This is useful
when you don't need exclusive access to a file for any reason
and need not restrict other processes.
Examples
FOPEN 1,"FILE.DAT",O_RD,S_DN ' Do not deny other
processes any access
FOR i = 1 TO 10
FGET 1,s
PRINTLN s
NEXT
FCLOSE 1 ' Close the file and allow others to open
it in any mode
See Also
S_DB Constant, S_DR Constant, S_DW Constant
S_DR Constant
Function
Set the share deny read flag in a FCREATE/FOPEN/FAPPEND
statement.
Value
1 = 1b = 1o = 1h
Remarks
DOS 3.1 or later (which is what is required by PCBoard) allows
processes to decide what mode of file sharing should be allowed.
This constant allows you to specify that other processes may
open the same file, but that they may not open it for read
access, from the time you open the file to the time you close
the file.
Examples
FOPEN 1,"FILE.DAT",O_RD,S_DR ' Deny other processes
read access
FOR i = 1 TO 10
FGET 1,s
PRINTLN s
NEXT
FCLOSE 1 ' Close the file and allow others to open
it in any mode
See Also
S_DB Constant, S_DN Constant, S_DW Constant
S_DW Constant
Function
Set the share deny write flag in a FCREATE/FOPEN/FAPPEND
statement.
Value
2 = 10b = 2o = 2h
Remarks
DOS 3.1 or later (which is what is required by PCBoard) allows
processes to decide what mode of file sharing should be allowed.
This constant allows you to specify that other processes may
open the same file, but that they may not open it for write
access, from the time you open the file to the time you close
the file. This is useful when you want to ensure that data will
not change while you are reading it.
Examples
FOPEN 1,"FILE.DAT",O_RD,S_DW ' Deny other processes
write access
FOR i = 1 TO 10
FGET 1,s
PRINTLN s
NEXT
FCLOSE 1 ' Close the file and allow others to open
it in any mode
See Also
S_DB Constant, S_DN Constant, S_DR Constant
TEMPPATH() Function
Function
Return the path to the temporary work directory as defined in
PCBSetup.
Syntax
TEMPPATH()
No arguments are required
Return Type & Value
STRING Returns the path of the node temporary work files
area.
Remarks
This function will return the path where temporary work files
should be created as defined in PCBSetup. This path is a good
place for small temporary files that need not be kept
permanently since it often points to a RAM drive or other fast
local storage.
Examples
INTEGER rc
SHELL TRUE,rc,"DIR",">"+TEMPPATH()+"TMPDIR"
DISPFILE TEMPPATH()+"TMPDIR",DEFS
DELETE TEMPPATH()+"TMPDIR"
See Also
TIME Type
Function
Declare one or more variables of type time.
Syntax
TIME var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])]
var The name of a variable to declare. Must start with
a letter [A-Z] which may be followed by letters, digits [0-9] or
the underscore [_]. May be of any length but only the first 32
characters are used.
arr The name of an array variable to declare. The same
naming conventions as var are used.
s The size (0-based) of an array variable dimension.
Any constant integer expression is allowed.
Remarks
TIME variables are stored as seconds elapsed since midnight.
Valid times are 0 (00:00:00) through 86399 (23:59:59). It is
stored internally as a four byte unsigned long integer. If a
TIME is assigned to or from an INTEGER type then the seconds
since midnight (0-86399) is assigned. If a TIME is assigned to
a STRING type then it is automatically converted to the
following format: "HH:MM:SS", where HH is the two digit hour
(00-23), MM is the two digit minute (00-59), and SS is the two
digit second (00-59). If a foreign language is in use that uses
a different time format (for example, "HH.MM.SS") then that will
be taken into account. If a STRING is assigned to a TIME then
PPL will do it's best to convert the string back to the
appropriate time. All other types, when assigned to or from a
TIME, will be converted to an INTEGER first before being
assigned to or from the TIME type.
Examples
TIME tob, now, pageHours(2), hourList(24)
See Also
BOOLEAN Type, DATE Type, INTEGER Type, MONEY Type, STRING Type
TIME() Function
Function
Get the current time.
Syntax
TIME()
No arguments are required
Return Type & Value
TIME Returns the current time.
Remarks
The time returned is represented internally as the number of
seconds elapsed since midnight. It may be used as is (for
display, storage or as an argument to another function or
statement) or assigned to an integer for arithmetic purposes.
00:00:00 (midnight) has a value of 0, 00:00:01 a value of 1,
00:01:00 a value of 60, 01:00:00 a value of 3600, etc, until
23:59:59 which has a value of 86399.
Examples
PRINTLN "The time is ",TIME()
See Also
TIMEAP() Function
Function
Converts a time value to a 12-hour AM/PM formatted string.
Syntax
TIMEAP(texp)
texp Any time expression.
Return Type & Value
STRING Returns a string formatted with the time specified
by texp in a 12-hour AM/PM format.
Remarks
TIME values are, by default, formatted for military time
("HH:MM:SS") when displayed or assigned to a string variable.
You may wish to format them in a 12-hour AM/PM format in some
circumstances, however. This function perform the conversion
and format the time in "HH:MM:SS XM" format (HH = hour, MM =
minute, SS = second, X = A or P).
Examples
PRINTLN "The current time is ",TIMEAP(TIME())
See Also
TOKCOUNT() Function
Function
Access the number of tokens pending.
Syntax
TOKCOUNT()
No arguments are required
Return Type & Value
INTEGER Returns the number of tokens available.
Remarks
Parameter passing between PCBoard and PPL applications (and
between PPL applications) and command line parsing is
accomplished via tokens. This function will return the number
of tokens available via the GETTOKEN statement and the
GETTOKEN() function. The value returned by this will be
decremented after each token is retrieved until it reaches 0 (no
more tokens available). The TOKENIZE function will overwrite
any pending tokens with new tokens and reinitialize this
function to the new number. Finally, the TOKENSTR() function
will clear this function to 0 and return all tokens in a string
with semi-colons separating individual tokens.
Examples
PRINTLN "There are ",TOKCOUNT()," tokens"
WHILE (TOKCOUNT() > 0) PRINTLN GETTOKEN()
See Also
TOKENIZE Statement
Function
Split up a string into tokens separated by semi-colons or
spaces.
Syntax
TOKENIZE sexp
sexp Any string expression.
Remarks
One of the strongest features of PCBoard is it's ability to take
a series of stacked parameters from a command line and use them
all at once instead of requiring the user to navigate a series
of menus and select one option at each step of the way. The
TOKENIZE statement is the PPL equivalent of what PCBoard uses to
break a command line into individual commands (tokens). The
number of tokens available may be accessed via the TOKCOUNT()
function, and each token may be accessed, one at a time, by the
GETTOKEN statement and/or the GETTOKEN() function.
Examples
STRING cmdline
INPUT "Command",cmdline
TOKENIZE cmdline
PRINTLN "You entered ",TOKCOUNT()," tokens"
WHILE (TOKCOUNT() > 0) PRINTLN "Token:
",CHR(34),GETTOKEN(),CHR(34)
See Also
GETTOKEN Statement, GETTOKEN() Function, TOKCOUNT() Function,
TOKENSTR() Function
TOKENSTR() Function
Function
Rebuild and return a previously tokenized string.
Syntax
TOKENSTR()
No arguments are required
Return Type & Value
STRING Returns the rebuilt string that was previously
tokenized.
Remarks
One of the strongest features of PCBoard is it's ability to take
a series of stacked parameters from a command line and use them
all at once instead of requiring the user to navigate a series
of menus and select one option at each step of the way. The
TOKENIZE statement is the PPL equivalent of what PCBoard uses to
break a command line into individual commands (tokens). This
function will take all pending tokens and build a string with
appropriate token separators. For example, the string "R A S"
would be broken into three separate tokens; "R", "A" and "S".
TOKENSTR() would take those tokens and return the following
string: "R;A;S". Note that, regardless of the separator used
in the original string, the semi-colon character will be used in
the rebuilt string.
Examples
STRING cmdline
INPUT "Command",cmdline
TOKENIZE cmdline
PRINTLN "You entered ",TOKCOUNT()," tokens"
PRINTLN "Original string: ",cmdline
PRINTLN " TOKENSTR(): ",TOKENSTR()
See Also
GETTOKEN Statement, GETTOKEN() Function, TOKCOUNT() Function,
TOKENIZE Statement
TRIM() Function
Function
Trim a specified character from both ends of a string.
Syntax
TRIM(str,ch)
str Any string expression.
ch A string with the character to strip from both ends
of str.
Return Type & Value
STRING Returns the trimmed str.
Remarks
A common need in programming is to strip leading and/or trailing
spaces (or other characters). This function will strip a
specified character from both ends of a string and return the
trimmed string.
Examples
STRING s
LET s = " TEST "
PRINTLN TRIM(s," ") ' Will print "TEST"
PRINTLN TRIM(".....DA"+"TA.....",".") ' Will print
"DATA"
PRINTLN TRIM(".....DA"+"TA....."," ") ' Will print
".....DATA....."
See Also
LTRIM() Function, RTRIM() Function
TRUE Constant
Function
To provide a named constant for the boolean true value in
boolean expressions.
Value
1 = 1b = 1o = 1h
Remarks
BOOLEAN logic is based on two values: TRUE (1) and FALSE (0).
The literal numeric constants 0 and 1 may be used in
expressions, or you may use the predefined named constants TRUE
and FALSE. They make for more readable, maintainable code and
have no more overhead than any other constant value at run time.
Examples
BOOLEAN flag
LET flag = TRUE
WHILE (!flag) DO
INPUTSTR
"Text",s,@X0E,60,"ABCDEFGHIJKLMNOPQRSTUVWXYZ
",UPCASE
PRINTLN s
IF (s = "QUIT") LET flag = FALSE
ENDWHILE
See Also
FALSE Constant
UN_...() Function
Function
Get a piece of information about a node.
Syntax
UN_...()
No arguments are required
UN_ should be followed by one of the following: CITY, NAME,
OPER, or STAT.
Return Type & Value
STRING Returns a string with the desired piece of
information.
Remarks
There are actually four different functions that return
information from the USERNET.XXX file. UN_CITY() will return
the city field, UN_NAME() will return the user name field,
UN_OPER() will return the operation text field, and UN_STAT()
will return the status field. The information returned by these
functions is only meaningful after executing the RDUNET
statement for a specific node.
Examples
RDUNET PCBNODE()
WRUNET
PCBNODE(),UN_STAT(),UN_NAME(),UN_CITY(),"Running
"+PPENAME(),""
RDUNET 1
WRUNET
1,UN_STAT(),UN_NAME(),UN_CITY(),UN_OPER(),"Hello
there node 1"
See Also
RDUNET Statement, WRUNET Statement
UPCASE Constant
Function
Set the force uppercase flag in an INPUTSTR or PROMPTSTR
statement.
Value
8 = 1000b = 10o = 8h
Remarks
The INPUTSTR and PROMPTSTR statements have the ability to force
all input characters to uppercase. This is useful in getting
case insensitive replies from the user. If this flag is used,
you need not pass lowercase valid characters as they will be
automatically converted at runtime. If this flag is not used
and you need to input alphabetic characters, you should pass
both lowercase and uppercase characters in the valid character
string.
Examples
STRING s
WHILE (s <> "QUIT") DO
INPUTSTR
"Text",s,@X0E,60,"ABCDEFGHIJKLMNOPQRSTUVWXYZ
",UPCASE
PRINTLN s
ENDWHILE
See Also
INPUTSTR Statement, PROMPTSTR Statement
UPPER() Function
Function
Converts lowercase characters in a string to uppercase.
Syntax
UPPER(sexp)
sexp Any string expression.
Return Type & Value
STRING Returns sexp with all lowercase characters converted
to uppercase.
Remarks
Although "STRING" is technically different from "string" (ie,
the computer doesn't recognize them as being the same because
one is uppercase and the other is lowercase), it is often
necessary to save, display or compare information in a case
insensitive format. This function will return a string with all
lowercase characters converted to uppercase. So, using the
above example, UPPER("string") would return "STRING".
Examples
STRING s
WHILE (UPPER(s) <> "QUIT") DO
INPUT "Text",s
PRINTLN LOWER(s)
ENDWHILE
See Also
LOWER() Function
U_ADDR() VARIABLE ARRAY
Function
Allow reading and writing of the current users address
information.
Type & Value
STRING
Subscript 0 Address Line 1 (50 characters max).
Subscript 1 Address Line 2 (50 characters max).
Subscript 2 City (25 characters max).
Subscript 3 State (10 characters max).
Subscript 4 ZIP Code (10 characters max).
Subscript 5 Country (15 characters max).
Remarks
This array is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that the array is empty until a GETUSER
statement is processed and that changes are not written until a
PUTUSER statement is processed. Additionally, the array will
only have meaningful information if the address PSA is
installed. The existence of the address PSA may be checked with
the PSA() function.
Examples
IF (PSA(3)) THEN
GETUSER
INPUT "Addr 1",U_ADDR(0)
INPUT "Addr 2",U_ADDR(1)
INPUT "City ",U_ADDR(2)
INPUT "State ",U_ADDR(3)
INPUT "ZIP ",U_ADDR(4)
INPUT "Cntry ",U_ADDR(5)
PUTUSER
ENDIF
See Also
GETUSER Statement, PSA() Function, PUTUSER Statement
U_ALIAS VARIABLE
Function
Allow reading and writing of the current users alias.
Type & Value
STRING The current users alias (25 characters max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. Additionally, it will only have
meaningful information if the alias PSA is installed. The
existence of the alias PSA may be checked with the PSA()
function.
Examples
IF (PSA(1)) THEN
GETUSER
PRINTLN "Your alias is ",U_ALIAS
ELSE
PRINTLN "Your name is ",U_NAME()
ENDIF
See Also
GETUSER Statement, PSA() Function, PUTUSER Statement
U_BDL() Function
Function
Access the total number of bytes downloaded by the current user.
Syntax
U_BDL()
No arguments are required
Return Type & Value
INTEGER Returns the current users total bytes downloaded.
Remarks
This function will return information that can be useful in
modifying PCBoard's built in ratio management system and the
view user information command. Of course, it is not limited to
that; anywhere you need to know how many bytes the current user
has downloaded, this function will provide that information.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You have ULed ",U_BUL()," bytes and DLed
",U_BDL()," bytes."
See Also
U_BDLDAY() Function
Function
Access the number of bytes downloaded by the current user today.
Syntax
U_BDLDAY()
No arguments are required
Return Type & Value
INTEGER Returns the current users bytes downloaded today.
Remarks
This function will return information that can be useful in
modifying PCBoard's built in ratio management system and the
view user information command. Of course, it is not limited to
that; anywhere you need to know how many bytes the current user
has downloaded today, this function will provide that
information. Unlike the predefined U_... user variables, this
function does not require the use of GETUSER to return valid
information.
Examples
PRINTLN "You have downloaded ",U_BDLDAY()," bytes
today."
See Also
U_BDPHONE VARIABLE
Function
Allow reading and writing of the current users business/data
phone number.
Type & Value
STRING The current users business/data phone number (13
characters max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN " Home/Voice Phone Number: ",U_HVPHONE
PRINTLN "Business/Data Phone Number: ",U_BDPHONE
See Also
GETUSER Statement, PUTUSER Statement
U_BUL() Function
Function
Access the total number of bytes uploaded by the current user.
Syntax
U_BUL()
No arguments are required
Return Type & Value
INTEGER Returns the current users total bytes uploaded.
Remarks
This function will return information that can be useful in
modifying PCBoard's built in ratio management system and the
view user information command. Of course, it is not limited to
that; anywhere you need to know how many bytes the current user
has uploaded, this function will provide that information.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You have ULed ",U_BUL()," bytes and DLed
",U_BDL()," bytes."
See Also
U_CITY VARIABLE
Function
Allow reading and writing of the current users city information.
Type & Value
STRING The current users city information (24 characters
max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. Note that this information is separate
from the address PSA and does not require that the address PSA
be installed.
Examples
GETUSER
LET U_CITY = "Timbuktu"
PRINTLN "You are now from Timbuktu! :)"
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_CLS VARIABLE
Function
Allow reading and writing of the current users message clear
screen flag.
Type & Value
BOOLEAN The current users clear screen flag status (TRUE or
FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning on the message clear screen
flag..."
LET U_CLS = TRUE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_CMNT1 VARIABLE
Function
Allow reading and writing of the current users comment field.
Type & Value
STRING The current users comment field (30 characters max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. Note that this information is separate
from the notes PSA (though similar) and does not require that
the notes PSA be installed.
Examples
GETUSER
PRINTLN " User Comment: ",U_CMNT1
PRINTLN "SysOp Comment: ",U_CMNT2
See Also
GETUSER Statement, PUTUSER Statement
U_CMNT2 VARIABLE
Function
Allow reading and writing of the current users SysOp comment
field.
Type & Value
STRING The current users SysOp comment field (30 characters
max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. Note that this information is separate
from the notes PSA (though similar) and does not require that
the notes PSA be installed.
Examples
GETUSER
PRINTLN " User Comment: ",U_CMNT1
PRINTLN "SysOp Comment: ",U_CMNT2
See Also
GETUSER Statement, PUTUSER Statement
U_DEF79 VARIABLE
Function
Allow reading and writing of the current users message editor
default width flag.
Type & Value
BOOLEAN The current users default editor width flag status
(TRUE or FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning on the wide message editor
flag..."
LET U_DEF79 = TRUE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_EXPDATE VARIABLE
Function
Allow reading and writing of the current users subscription
expiration date.
Type & Value
DATE The current users subscription expiration date.
Remarks
This DATE is set with information from the current users record
when the GETUSER statement is executed. It may then be changed
and written back to the users record with the PUTUSER statement.
Note that it is undefined until a GETUSER statement is processed
and that changes are not written until a PUTUSER statement is
processed.
Examples
GETUSER
PRINTLN "Your subscription will expire on
",U_EXPDATE
See Also
GETUSER Statement, PUTUSER Statement
U_EXPERT VARIABLE
Function
Allow reading and writing of the current users expert status
flag.
Type & Value
BOOLEAN The current users expert flag status (TRUE or
FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning off expert mode..."
LET U_EXPERT = FALSE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_EXPSEC VARIABLE
Function
Allow reading and writing of the current users expired security
level.
Type & Value
INTEGER The current users security level (0 - 255).
Remarks
This INTEGER is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Your security after subscription
expiration will be ",U_SEC
See Also
GETUSER Statement, PUTUSER Statement
U_FDL() Function
Function
Access the total number of files downloaded by the current user.
Syntax
U_FDL()
No arguments are required
Return Type & Value
INTEGER Returns the current users total files downloaded.
Remarks
This function will return information that can be useful in
modifying PCBoard's built in ratio management system and the
view user information command. Of course, it is not limited to
that; anywhere you need to know how many files the current user
has downloaded, this function will provide that information.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You have ULed ",U_FUL()," bytes and DLed
",U_FDL()," files."
See Also
U_FSE VARIABLE
Function
Allow reading and writing of the current users full screen
editor default flag.
Type & Value
BOOLEAN The current users full screen editor default flag
status (TRUE or FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning on full screen editor as
default..."
LET U_FSE = TRUE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_FSEP VARIABLE
Function
Allow reading and writing of the current users full screen
editor prompt flag.
Type & Value
BOOLEAN The current users full screen editor prompt flag
status (TRUE or FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning off full screen editor
prompting..."
LET U_FSEP = FALSE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_FUL() Function
Function
Access the total number of files uploaded by the current user.
Syntax
U_FUL()
No arguments are required
Return Type & Value
INTEGER Returns the current users total files uploaded.
Remarks
This function will return information that can be useful in
modifying PCBoard's built in ratio management system and the
view user information command. Of course, it is not limited to
that; anywhere you need to know how many files the current user
has uploaded, this function will provide that information.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You have ULed ",U_FUL()," bytes and DLed
",U_FDL()," files."
See Also
U_HVPHONE VARIABLE
Function
Allow reading and writing of the current users home/voice phone
number.
Type & Value
STRING The current users home/voice phone number (13
characters max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN " Home/Voice Phone Number: ",U_HVPHONE
PRINTLN "Business/Data Phone Number: ",U_BDPHONE
See Also
GETUSER Statement, PUTUSER Statement
U_INCONF() Function
Function
Determine if a user is registered in a conference.
Syntax
U_INCONF(rec,conf)
rec An integer expression with the record number of the
user to check.
conf An integer expression with the conference number to
check.
Return Type & Value
BOOLEAN Returns TRUE if the user is registered in the
specified conference, FALSE otherwise.
Remarks
It is sometimes necessary to know if a user is registered in a
conference (for example, when entering a message to a particular
user). This function will return TRUE if the user is registered
in the conference specified. Before calling this function you
need to find the users record number from the USERS file with
the U_RECNUM() function.
Examples
INTEGER i,rec
STRING un,ynStr(1)
LET ynStr(0) = "NO"
LET ynStr(1) = "YES"
INPUT "User name",un
NEWLINE
LET rec = U_RECNUM(un)
FOR i = 1 TO 10
PRINTLN un," in conf ",i,":
",ynStr(U_INCONF(i,rec))
NEXT
See Also
U_RECNUM() Function
U_LDATE() Function
Function
Access the last log on date of a user.
Syntax
U_LDATE()
No arguments are required
Return Type & Value
DATE Returns the current users last log on date.
Remarks
PCBoard tracks the last log on date for each user. This
function will return that date for the user currently online.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You last logged on ",U_LDATE(),"."
See Also
U_LDIR() Function
Function
Access the latest file date found in a file scan by a user.
Syntax
U_LDIR()
No arguments are required
Return Type & Value
DATE Returns the latest file date found by the current user.
Remarks
PCBoard tracks the latest file found by each user. This
function will return that date for the user currently online.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "Latest file found was dated ",U_LDIR(),"."
See Also
U_LOGONS() Function
Function
Access the total number of system logons by the current user.
Syntax
U_LOGONS()
No arguments are required
Return Type & Value
INTEGER Returns the current users total system logons.
Remarks
PCBoard tracks the total number of logons for each user. This
function will return that number for the user currently online.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You have logged on to @BOARDNAME@
",U_LOGONS()," times."
See Also
U_LONGHDR VARIABLE
Function
Allow reading and writing of the current users long message
header flag.
Type & Value
BOOLEAN The current users long message header flag status
(TRUE or FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning on long message headers..."
LET U_LONGHDR = TRUE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_LTIME() Function
Function
Access the time of day that a user last logged on.
Syntax
U_LTIME()
No arguments are required
Return Type & Value
TIME Returns the time of day of the current users last log on.
Remarks
PCBoard tracks the last time of day of the last log on for each
user. This function will return that time for the user
currently online. Unlike the predefined U_... user variables,
this function does not require the use of GETUSER to return
valid information.
Examples
PRINTLN "You last logged on at ",U_LTIME(),"."
See Also
U_MSGRD() Function
Function
Access the total number of messages read by the current user.
Syntax
U_MSGRD()
No arguments are required
Return Type & Value
INTEGER Returns the current users total messages read.
Remarks
PCBoard tracks the total number of messages read by each user.
This function will return that number for the user currently
online. One quick idea for use: a message/file ratio
enforcement door. Unlike the predefined U_... user variables,
this function does not require the use of GETUSER to return
valid information.
Examples
IF ((U_MSGRD()+U_MSGWR())/U_FDL() > 10) THEN
PRINTLN "You need to do more messaging!!!"
END
ENDIF
See Also
U_MSGWR() Function
Function
Access the total number of messages written by the current user.
Syntax
U_MSGWR()
No arguments are required
Return Type & Value
INTEGER Returns the current users total messages written.
Remarks
PCBoard tracks the total number of messages written by each
user. This function will return that number for the user
currently online. One quick idea for use: a message/file ratio
enforcement door. Unlike the predefined U_... user variables,
this function does not require the use of GETUSER to return
valid information.
Examples
IF ((U_MSGRD()+U_MSGWR())/U_FDL() > 10) THEN
PRINTLN "You need to do more messaging!!!"
END
ENDIF
See Also
U_NAME() Function
Function
Access the current users name.
Syntax
U_NAME()
No arguments are required
Return Type & Value
STRING Returns a string with the current users name.
Remarks
Perhaps the most important piece of information about a caller
is his name. The user name differentiates a user from every
other user on the BBS and can be used to track PPE user
information that must be kept separate from all other users
information. Unlike the predefined U_... user variables, this
function does not require the use of GETUSER to return valid
information.
Examples
IF (U_NAME() = "JOHN DOE) THEN
PRINTLN "I know who you are! Welcome!"
GETUSER
LET U_SEC = 110
PUTUSER
PRINTLN "Automatically upgraded!"
ENDIF
See Also
U_NOTES() VARIABLE ARRAY
Function
Allow reading and writing of current user notes.
Type & Value
STRING
Subscript 0-4 SysOp defineable user notes (60
characters max).
Remarks
This array is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that the array is empty until a GETUSER
statement is processed and that changes are not written until a
PUTUSER statement is processed. Additionally, the array will
only have meaningful information if the notes PSA is installed.
The existence of the notes PSA may be checked with the PSA()
function.
Examples
INTEGER i
IF (PSA(6)) THEN
GETUSER
FOR i = 0 TO 4
PRINTLN "Note ",i+1,": ",U_NOTES(i)
NEXT
ENDIF
See Also
GETUSER Statement, PSA() Function, PUTUSER Statement
U_PAGELEN VARIABLE
Function
Allow reading and writing of the current users page length
setting.
Type & Value
INTEGER The current users page length (0 - 255).
Remarks
This integer is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Your page length was ",U_PAGELEN
LET U_PAGELEN = 20
PRINTLN "Your page length is now ",U_PAGELEN
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_PWD VARIABLE
Function
Allow reading and writing of the current users password.
Type & Value
STRING The current users password (12 characters max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. A mask of valid characters that may be
used in the U_PWD variable is available via the MASK_PWD
function.
Examples
STRING s
INPUT "Enter Password",s,@X0E,12,MASK_PWD(),UPCASE
GETUSER
IF (s <> U_PWD) THEN
PRINTLN "Sorry, hanging up"
HANGUP
ENDIF
See Also
GETUSER Statement, MASK_PWD() Function, PUTUSER Statement
U_PWDEXP VARIABLE
Function
Allow reading and writing of the current users password
expiration date.
Type & Value
DATE The current users password expiration date.
Remarks
This DATE is set with information from the current users record
when the GETUSER statement is executed. It may then be changed
and written back to the users record with the PUTUSER statement.
Note that it is undefined until a GETUSER statement is processed
and that changes are not written until a PUTUSER statement is
processed. Additionally, it will only have meaningful
information if the password PSA is installed. The existence of
the password PSA may be checked with the PSA() function.
Examples
IF (PSA(4)) THEN
GETUSER
PRINTLN U_PWDEXP-DATE()," until current password
expiration"
LET U_PWDEXP = DATE()+30
PRINTLN "You now have 30 days until you *MUST*
change you password."
PUTUSER
ENDIF
See Also
GETUSER Statement, PSA() Function, PUTUSER Statement
U_PWDHIST() Function
Function
Access the last three passwords used by the current user.
Syntax
U_PWDHIST(num)
num The number of the password from the history to
return (1 through 3).
Return Type & Value
STRING Returns the specified password from the history (1
for the most recent, 3 for the least recent).
Remarks
PCBoard has the ability to track the last three passwords used
by each user. This function will return one of those passwords
from the history for the user currently online. Unlike the
predefined U_... user variables, this function does not require
the use of GETUSER to return valid information. However, it
does require that the password PSA has been installed to return
meaningful information. The existence of the password PSA may
be checked via the PSA() function.
Examples
INTEGER i
IF (PSA(4)) THEN
FOR i = 1 TO 3
PRINTLN "Password history ",i,":
",U_PWDHIST(i)
NEXT
ENDIF
See Also
PSA() Function
U_PWDLC() Function
Function
Access the last date the user changed his password.
Syntax
U_PWDLC()
No arguments are required
Return Type & Value
DATE Returns the last date the user changed his password.
Remarks
PCBoard has the ability to track the last date of a password
change for each user. This function will return that date for
the user currently online. Unlike the predefined U_... user
variables, this function does not require the use of GETUSER to
return valid information. However, it does require that the
password PSA has been installed to return meaningful
information. The existence of the password PSA may be checked
via the PSA() function.
Examples
IF (PSA(4)) PRINTLN "You last changed your password
on ",U_PWDLC(),"."
See Also
PSA() Function
U_PWDTC() Function
Function
Access the number of times the user has changed his password.
Syntax
U_PWDTC()
No arguments are required
Return Type & Value
INTEGER Returns the number of times the user has changed his
password.
Remarks
PCBoard has the ability to track the total number of times each
user changes his password. This function will return that count
for the user currently online. Unlike the predefined U_... user
variables, this function does not require the use of GETUSER to
return valid information. However, it does require that the
password PSA has been installed to return meaningful
information. The existence of the password PSA may be checked
via the PSA() function.
Examples
IF (PSA(4)) THEN
PRINTLN "You have changed your password
",U_PWDTC()," times."
ENDIF
See Also
PSA() Function
U_RECNUM() Function
Function
Determine if a user is registered on the system and what the
record number is.
Syntax
U_RECNUM(user)
user A string expression with the user name to search
for.
Return Type & Value
INTEGER Returns the record number of the user in the USERS
file if found or -1 if not found.
Remarks
This function serves two purposes. The first is to determine
whether or not a given user name is registered on the system.
If the value -1 is returned the user isn't in the user files.
The second use is to get the users record number for the
U_INCONF() function to determine whether or not a user is
registered in a given conference.
Examples
INTEGER i,rec
STRING un,ynStr(1)
LET ynStr(0) = "NO"
LET ynStr(1) = "YES"
INPUT "User name",un
NEWLINE
LET rec = U_RECNUM(un)
FOR i = 1 TO 10
PRINTLN un," in conf ",i,":
",ynStr(U_INCONF(i,rec))
NEXT
See Also
U_INCONF() Function
U_SCROLL VARIABLE
Function
Allow reading and writing of the current users multi-screen
message scroll flag.
Type & Value
BOOLEAN The current users scroll flag status (TRUE or
FALSE).
Remarks
This BOOLEAN is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Turning off message scrolling..."
LET U_SCROLL = FALSE
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_SEC VARIABLE
Function
Allow reading and writing of the current users security level.
Type & Value
INTEGER The current users security level (0 - 255).
Remarks
This INTEGER is set with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is undefined until a GETUSER statement
is processed and that changes are not written until a PUTUSER
statement is processed.
Examples
GETUSER
PRINTLN "Raising your security to level 20..."
LET U_SEC = 20
PUTUSER
PRINTLN "Automatic upgrade complete!"
See Also
GETUSER Statement, PUTUSER Statement
U_STAT() Function
Function
Access a statistic about the current user.
Syntax
U_TIMEON(stat)
stat The statistic to retrieve (1 through 15).
Return Type & Value
DATE Returns the first date the user called the system if stat
is 1.
INTEGER Returns one of the following for all other values of
stat:
2 The number of times the user has paged the SysOp;
3 The number of group chats the user has participated
in;
4 The number of comments left by the user;
5 The number of 300 bps connects by the user;
6 The number of 1200 bps connects by the user;
7 The number of 2400 bps connects by the user;
8 The number of connects by the user greater than 2400
bps and less than or equal to 9600 bps (9600 bps >= connect
speed > 2400 bps);
9 The number of connects by the user greater than 9600
bps and less than or equal to 14,400 bps (14,400 bps >= connect
speed > 9600 bps);
10 The number of security violations by the user;
11 The number of "not registered in conference"
warnings to the user;
12 The number of times the user's download limit has
been reached;
13 The number of "file not found" warnings to the user;
14 The number of password errors to access the user's
account;
15 The number of verify errors to access the user's
account.
Remarks
PCBoard has the ability to track a number of statistics about
the user. This function will return the desired statistic for
the user currently online. Unlike the predefined U_... user
variables, this function does not require the use of GETUSER to
return valid information. However, it does require that the
statistics PSA has been installed to return meaningful
information. The existence of the statistics PSA may be checked
via the PSA() function.
Examples
STRING label
INTEGER i
FOPEN 1,PPEPATH()+"STATTEXT",O_RD,S_DN
FOR i = 1 TO 15
FGET 1,label
PRINTLN label," - ",U_STAT(i)
NEXT
FCLOSE 1
See Also
PSA() Function
U_TIMEON() Function
Function
Access the users time online today in minutes.
Syntax
U_TIMEON()
No arguments are required
Return Type & Value
INTEGER Returns the users time online today in minutes.
Remarks
PCBoard tracks the users time online each day. This function
will return the elapsed time for the user currently online.
Unlike the predefined U_... user variables, this function does
not require the use of GETUSER to return valid information.
Examples
PRINTLN "You have been online for ",U_TIMEON(),"
total minutes today."
See Also
U_TRANS VARIABLE
Function
Allow reading and writing of the current users default transfer
protocol letter.
Type & Value
STRING The current users default transfer protocol letter
(1 character max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. Valid characters that may be used in
the U_TRANS variable are A through Z and 0 through 9.
Examples
GETUSER
PRINTLN "Your default file transfer protocol letter
is ",U_TRANS
LET U_TRANS = "N" ' Set to no default protocol
PRINTLN "Default file transfer protocol letter set
to None"
PUTUSER
See Also
GETUSER Statement, PUTUSER Statement
U_VER VARIABLE
Function
Allow reading and writing of the current users verification
string.
Type & Value
STRING The current users verification string (25 characters
max).
Remarks
This STRING is filled with information from the current users
record when the GETUSER statement is executed. It may then be
changed and written back to the users record with the PUTUSER
statement. Note that it is empty until a GETUSER statement is
processed and that changes are not written until a PUTUSER
statement is processed. Additionally, it will only have
meaningful information if the verification PSA is installed.
The existence of the verification PSA may be checked with the
PSA() function.
Examples
STRING s
IF (PSA(2)) THEN
GETUSER
PRINTLN "Enter verification information"
INPUT "",s
IF (s <> U_VER) HANGUP
ELSE
PRINTLN "No verification information available"
ENDIF
See Also
GETUSER Statement, PSA() Function, PUTUSER Statement
VALCC() Function
Function
Tests a string for credit card number format validity.
Syntax
VALCC(sexp)
sexp Any string expression.
Return Type & Value
BOOLEAN Returns TRUE if the string is a valid credit card
number format, FALSE otherwise.
Remarks
This function will take a string and attempt to identify it as a
credit card number. If the number is invalid for any reason
(insufficient digits or bad checksum, primarily) then this
function will return FALSE, otherwise it will return TRUE.
Examples
STRING s
WHILE (!VALCC(s)) DO
INPUT "CC #",s
NEWLINES 2
ENDWHILE
PRINTLN CCTYPE(s)," - ",FMTCC(s)
See Also
CCTYPE() Function, FMTCC() Function, VALDATE() Function,
VALTIME() Function
VALDATE() Function
Function
Tests a string for date format validity.
Syntax
VALDATE(sexp)
sexp Any string expression.
Return Type & Value
BOOLEAN Returns TRUE if the string is a valid date format,
FALSE otherwise.
Remarks
PPL does it best to convert incompatible types, as needed,
automatically. Converting a STRING type to a DATE type is
particularly problematic because of the virtually unlimited
numbers of strings possible. This function checks to make sure
that the hour is from 0 to 23, the minute is from 0 to 59, and
the second (optional) is from 0 to 59. Also, each field
(hours/minutes/seconds) must be separated by a colon. If the
string matches these requirements then the string is considered
valid and TRUE is returned. Any other string will result in a
FALSE value being returned.
Examples
STRING s
WHILE (!VALTIME(s)) DO
INPUT "Time",s
NEWLINES 2
ENDWHILE
TIME t
LET t = s
PRINTLN s," ",t
See Also
VALCC() Function, VALDATE() Function
VALTIME() Function
Function
Tests a string for time format validity.
Syntax
VALTIME(sexp)
sexp Any string expression.
Return Type & Value
BOOLEAN Returns TRUE if the string is a valid time format,
FALSE otherwise.
Remarks
PPL does it best to convert incompatible types, as needed,
automatically. Converting a STRING type to a TIME type is
particularly problematic because of the virtually unlimited
numbers of strings possible. This function checks to make sure
that the hour is from 0 to 23, the minute is from 0 to 59, and
the second (optional) is from 0 to 59. Also, each field
(hours/minutes/seconds) must be separated by a colon. If the
string matches these requirements then the string is considered
valid and TRUE is returned. Any other string will result in a
FALSE value being returned.
Examples
STRING s
WHILE (!VALTIME(s)) DO
INPUT "Time",s
NEWLINES 2
ENDWHILE
TIME t
LET t = s
PRINTLN s," ",t
See Also
VALCC() Function, VALDATE() Function
VARADDR Statement
Function
Sets a variable to the complete address of another variable.
Syntax
VARADDR src,dest
src The variable to get the address of.
dest The variable to store the address in.
Remarks
This statement is primarily useful in conjunction with the
DOINTR statement. It may be necessary to give an interrupt the
address of a memory location that can be used to store
information. This statement will allow you to get the address
of a specified variable to pass to the DOINTR statement.
Examples
' Create subdirectory - DOS function 39h
INTEGER addr
STRING path
LET path = "C:\$TMPDIR$"
VARADDR path,addr
DOINTR 21h,39h,0,0,addr%10000h,0,0,0,addr/10000h,0
IF (REGCF() & (REGAX() = 3)) THEN
PRINTLN "Error: Path not found"
ELSE IF (REGCF() & (REGAX() = 5)) THEN
PRINTLN "Error: Access Denied"
ELSE IF (REGCF()) THEN
PRINTLN "Error: Unknown Error"
ELSE
PRINTLN "Directory successfully created..."
ENDIF
See Also
MKADDR() Function, VAROFF Statement, VARSEG Statement
VAROFF Statement
Function
Sets a variable to the offset address of another variable.
Syntax
VAROFF src,dest
src The variable to get the offset address of.
dest The variable to store the offset address in.
Remarks
This statement is primarily useful in conjunction with the
DOINTR statement. It may be necessary to give an interrupt the
address of a memory location that can be used to store
information. This statement will allow you to get the offset
address of a specified variable to pass to the DOINTR statement.
Examples
' Create subdirectory - DOS function 39h
INTEGER saddr, oaddr
STRING path
LET path = "C:\$TMPDIR$"
VARSEG path,saddr
VAROFF path,oaddr
DOINTR 21h,39h,0,0,oaddr,0,0,0,saddr,0
IF (REGCF() & (REGAX() = 3)) THEN
PRINTLN "Error: Path not found"
ELSE IF (REGCF() & (REGAX() = 5)) THEN
PRINTLN "Error: Access Denied"
ELSE IF (REGCF()) THEN
PRINTLN "Error: Unknown Error"
ELSE
PRINTLN "Directory successfully created..."
ENDIF
See Also
MKADDR() Function, VARADDR Statement, VARSEG Statement
VARSEG Statement
Function
Sets a variable to the segment address of another variable.
Syntax
VARSEG src,dest
src The variable to get the segment address of.
dest The variable to store the segment address in.
Remarks
This statement is primarily useful in conjunction with the
DOINTR statement. It may be necessary to give an interrupt the
address of a memory location that can be used to store
information. This statement will allow you to get the segment
address of a specified variable to pass to the DOINTR statement.
Examples
' Create subdirectory - DOS function 39h
INTEGER saddr, oaddr
STRING path
LET path = "C:\$TMPDIR$"
VARSEG path,saddr
VAROFF path,oaddr
DOINTR 21h,39h,0,0,oaddr,0,0,0,saddr,0
IF (REGCF() & (REGAX() = 3)) THEN
PRINTLN "Error: Path not found"
ELSE IF (REGCF() & (REGAX() = 5)) THEN
PRINTLN "Error: Access Denied"
ELSE IF (REGCF()) THEN
PRINTLN "Error: Unknown Error"
ELSE
PRINTLN "Directory successfully created..."
ENDIF
See Also
MKADDR() Function, VARADDR Statement, VAROFF Statement
VER() Function
Function
Get the version of PPL available.
Syntax
VER()
No arguments are required
Return Type & Value
INTEGER Returns the version number of PPL running.
Remarks
As time passes, new features will be added to PCBoard and PPL.
Of course, in order to utilize the new features, you must be
running a version of PCBoard that supports them. This function
will return the version of PCBoard (and PPL). For PCBoard
version 15.0 this value will be 1500. In other words, the major
version will be accessable via VER()/100, and the minor version
will be available via VER()%100. Everything documented herein
will be available for all versions greater than or equal to
1500. Future PPL features will be documented with the required
version.
Examples
IF (VER() < 1600) THEN
PRINTLN "PCBoard Version 16.0 required for this
PPE file"
END
ENDIF
FOO a,b,c,d,e ' Obviously, this is not a 15.0
statement
See Also
WAIT Statement
Function
Wait for the user to hit ENTER.
Syntax
WAIT
No arguments are required
Remarks
It is often necessary to pause in the display of information and
wait for the user to catch up. This statement allows you to
wait for the user to hit ENTER before continuing. It displays
prompt number 418 from the PCBTEXT file for the current language
to let the user know what is expected.
Examples
PRINTLN "Your account has expired!"
PRINTLN "You are about to be logged off"
WAIT
See Also
MORE Statement
WAITFOR Statement
Function
Wait for a specific string of text to come in from the modem.
Syntax
WAITFOR str,flag,sec
str Any string expression.
flag A variable to return the status.
sec An integer expression with the maximum number of
seconds to wait.
Remarks
This statement can be used to wait for specific replies to
questions, responses from terminal emulators and modem result
codes. If the text that is needed isn't received within the
specified time period, or if there is not a remote caller
online, flag will be set to FALSE. If the text is found, then
flag will be TRUE. If a remote caller is online this statement
will wait up to the maximum time for the text and return TRUE or
FALSE as appropriate. If the caller is local, it will
immediately return FALSE. Also, the text to wait for is not
case sensitive. "connect" will match "CONNECT".
Examples
BOOLEAN flag
KBDCHKOFF
CDCHKOFF
DTROFF
DELAY 18
DTRON
SENDMODEM "ATDT5551212" ' Please don't really dial
this number!
WAITFOR "CONNECT",flag,60
IF (!flag) SPRINLN "No connect found in 60 seconds"
CDCHKON
KBDCHKON
See Also
WHILE/ENDWHILE Statement
Function
Execute one or more statments while a condition is true.
Syntax
W H I L E ( b e x p ) s t a t e m e n t
- o r -
W H I L E ( b e x p ) D O
s t a t e m e n t ( s )
ENDWHLLE
bexp Any boolean expression.
statement Any valid PPL statement.
Remarks
Computers are known for their ability to perform monotonous
tasks quickly, efficiently, and accurately. What better way to
implement monotony than through a WHILE loop? The WHILE
statement supports two types of loops: logical and block. A
logical WHILE loop is a single statement; if a condition is
TRUE, execute a single statement and check again. A block WHILE
loop can be one or more statements. The start of a block WHILE
loop is differentiated from a logical WHILE loop by the DO
keyword immediately after the condition. At some point in the
loop some action must be taken that will make the condition
FALSE. If the condition never changes from TRUE to FALSE you
have what is known as an infinite loop; your computer will
appear to be hung, even though it is rapidly executing things
just as fast as it can. Be sure to thoroughly test all
programs, but especially programs with loops!
Examples
INTEGER i
LET i = 0
WHILE (i < 10) GOSUB sub
END
:sub
PRINTLN "i is ",i
INC i
RETURN
INTEGER i
LET i = 0
WHILE (i < 10) DO
PRINTLN "i is ",i
INC i
ENDWHILE
See Also
FOR/NEXT Statement, IF/ELSEIF/ELSE/ENDIF Statement
WORDWRAP Constant
Function
Set the word wrap flag in an INPUTSTR or PROMPTSTR statement.
Value
512 = 1000000000b = 1000o = 200h
Remarks
The INPUTSTR and PROMPTSTR statements have the ability to word
wrap from one input statement to the next input statement. If
you reach the end of the input field PCBoard will automatically
save the last word from the input field in an internal buffer.
The next input statement will use that saved word if both
statements used the WORDWRAP constant. If the passed variable
isn't empty or if an input statement is used that doesn't have
the WORDWRAP flag set then the saved word will not be used.
Examples
STRING s(5)
INTEGER i
CLS
FOR i = 1 TO 5
INPUTSTR "Line
"+STRING(i),s(i),@X0E,40,MASK_ASCII(),WORDWRAP+NEWL
INE
NEXT
CLS
FOR i = 1 TO 5
PRINTLN "Line ",i,": ",s(i)
NEXT
See Also
INPUTSTR Statement, PROMPTSTR Statement
WRUNET Statement
Function
Write information to the USERNET file for a specific node.
Syntax
WRUNET node,stat,name,city,oper,br
node An integer expression with the node to update.
stat A string expression with the new node status.
name A string expression with the new node user name.
city A string expression with the new node city.
oper A string expression with the new node operation
text.
br A string expression with the new node broadcast
text.
Remarks
To facilitate internode communications, a file named USERNET.XXX
is maintained with an entry for each node on the system. This
file is used by the BROADCAST command of PCBoard and to prevent
multiple simultaneous logins, among other things. This
statement may be used to change information for the current node
(for example, to update operation text during PPE execution) or
other nodes (for example, to broadcast a message).
Examples
RDUNET PCBNODE()
WRUNET
PCBNODE(),UN_STAT(),UN_NAME(),UN_CITY(),"Running
"+PPENAME(),""
RDUNET 1
WRUNET
1,UN_STAT(),UN_NAME(),UN_CITY(),UN_OPER(),"Hello
there node 1"
See Also
RDUNET Statement, UN_...() Function
WRUSYS Statement
Function
Write a USERS.SYS file out to disk.
Syntax
WRUSYS
No arguments are required
Remarks
Some DOOR applications require a USERS.SYS file to access
information about the caller. This statement allows you to
create that file prior to running an application via the SHELL
statement. Should the DOOR make changes to the USERS.SYS file,
you should use the RDUSYS statement after the SHELL to read the
changes back into memory. It should be noted that it is not
possible to create the USERS.SYS file with a TPA record with
this statement.
Examples
INTEGER ret
WRUSYS
SHELL FALSE,ret,"MYAPP.EXE",""
RDUSYS
See Also
RDUSYS Statement
XOR() Function
Function
Calculate the bitwise XOR (exclusive or) of two integer
arguments.
Syntax
AND(iexp1,iexp2)
iexp1 Any integer expression.
iexp2 Any integer expression.
Return Type & Value
INTEGER Returns the bitwise XOR of iexp1 and iexp2.
Remarks
This function may be used to toggle selected bits in an integer
expression by XORing the expression with a mask that has the
bits to toggle set to 1 and the bits to ignore set to 0.
Examples
' Toggle the bits in the low byte
PRINTLN XOR(1248h,00FFh)
' Toggle a flag
INTEGER flag
LET flag = XOR(flag,1)
See Also
AND() Function, NOT() Function, OR() Function
YEAR() Function
Function
Extracts the year from a specified date.
Syntax
YEAR(dexp)
dexp Any date expression.
Return Type & Value
INTEGER Returns the year from the specified date expression
(dexp). Valid return values are from 1900 to 2079.
Remarks
This function allows you to extract a particular piece of
information about a DATE value, in this case the year of the
date.
Examples
PRINTLN "This year is: ",YEAR(DATE())
See Also
DAY() Function, DOW() Function, MONTH() Function
YESCHAR() Function
Function
Get the yes response character for the current language.
Syntax
YESCHAR()
No arguments are required
Return Type & Value
STRING Returns the yes character for the current language.
Remarks
Support for foreign language yes/no responses can be easily
added by using this function to determine what an affirmative
response should be instead of hardcoding the english "Y"
character.
Examples
STRING ans
LET ans = YESCHAR()
INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO
IF (ans = NOCHAR()) END
See Also
NOCHAR() Function, YESNO Constant
YESNO Constant
Function
Set the international yes/no response flag in an INPUTSTR or
PROMPTSTR statement.
Value
16384 = 100000000000000b = 40000o = 4000h
Remarks
The INPUTSTR and PROMPTSTR statements have the ability to allow
a yes/no response to be entered in addition to any valid
characters passed to the statement. The extra characters
allowed are Y/N (or whatever characters were defined for the
current language; spanish would use S/N, french would use O/N,
etc). Note that you do not need to pass any valid characters to
use this flag; regardless of the other legal characters the
international Y/N characters will be allowed.
Examples
STRING ans
LET ans = NOCHAR()
INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO
IF (ans = NOCHAR()) END
See Also
INPUTSTR Statement, NOCHAR() Function, PROMPTSTR Statement,
YESCHAR() Function